Light
Dark
System

API Docs

API Endpoints

Retrieving usage statistics

Use this endpoint to retrieve statistics about your account's usage.

Request

GET https://api.upscope.io/v1.3/usage

Response

// HTTP 200
{
  "status": "ok",
  "usage": {
      "agents": {
          "last_30_days": 10,
          "today": 0
      },
      "session_counts": {
          "last_30_days": 20,
          "now": 0,
          "today": 0
      },
      "session_seconds": {
          "last_30_days": 5000,
          "today": 0
      },
      "visitors": {
          "last_24_hrs": 50000,
          "online_now": 400
      }
  }
}

Field

Type

Description

usage.agents.last_30_days

integer

Number of Agents who used Upscope in the last 30 days.

usage.agents.today

integer

Number of Agents who used Upscope in the last 24 hours.

usage.session_counts.last_30_days

integer

Number of Sessions in the last 30 days.

usage.session_counts.now

integer

Number of Sessions currently ongoing.

usage.session_counts.today

integer

Number of Sessions in the last 24 hours.

usage.session_seconds.last_30_days

integer

Number of Session seconds in the past 30 days.

usage.session_seconds.today

integer

Number of Session seconds in the past 24 hours.

usage.visitors.last_24_hrs

integer

Number of Visitors in the past 24 hours.

usage.visitors.online_now

integer

Number of Visitors online now.

Searching for a Visitor or retrieving a list of Visitors

Use this endpoint to search for a particular Visitor or to show a list of recently online Visitors.

Know the Visitor's ID?

If you know the Visitor's ID, avoid using the search functionality and instead use the direct endpoint, which will be considerably faster.

Need just 1 result?

Make sure to set max_results to 1. This will be considerably faster as our api service will be making a bunch of parallel requests to all the co-browsing regions you have enabled, and by setting to 1, it can respond to you as soon as it gets the first result.

Request

GET https://api.upscope.io/v1.3/list

Parameter

Type

Description

search

string

The search query in this format. If left empty, the latest Visitors will be returned.

max_results

number

The max number of results to return, up to 10. Defaults to 10.

Setting this to 1 will make the search faster.

Response

// HTTP 200
{
  "status": "ok",
  "visitors": [
    {
      "short_id": "1234",
      // ...
    }
  ]
}

Field

Type

Description

visitors

Visitor[]

List of Visitors matching the query.

visitors.sessions

Session[]

List of the Visitor's last 50 Sessions.

Retrieving a Visitor

Use this endpoint to retrieve a particular Visitor.

Request

GET https://api.upscope.io/v1.3/visitors/{visitor_id}

Parameter

Type

Description

{visitor_id}

String

The short id of the Visitor.

Response

// HTTP 200
{
  "status": "ok",
  "visitor": {
    "short_id": "1234",
    // ...
  }
}

Field

Type

Description

visitor

Visitor

The Visitor.

Errors

Code

Description

404

The Visitor does not exist.

Generating a link to start screen sharing with a Visitor

Use this endpoint to generate a Secure watch link that enables whoever opens it to start a co-browsing Session with the Visitor without needing to be logged into Upscope as an Agent.

The link doesn't last long

The link returned by this endpoint doesn't last long and it's not meant to be stored anywhere.
Ideally, the Agent will make a request to an endpoint on your server, which makes this request behind the scenes and redirects the Agent to the watch_url immediately.
Your integration should never rely on storing the Secure watch link anywhere for any length of time.
Learn more here.

Request

// POST https://api.upscope.io/v1.3/visitors/{visitor_id}/watch_url
{
  "branding": {
    "naked": true,
  },
  "permissions": {},
  "agent": {
    "id": "123",
    "name": "Joe Smith"
  },
  "metadata": {},
  "webhook_url": "https://example.com"
}

Parameter

Type

Description

{visitor_id}

string

The short id of the Visitor.

agent.id

string

The ID of the Agent

agent.name

string, optional

The name of the Agent

branding.naked

falsetrue, or "page_only"

If true, the Upscope logo will not be shown on the page. This is ideal if you want to display the page inside an iframe. Defaults to false. Can be set to page_only to remove everything, including the Agent's UI. You can then control the Session by post-messaging the iframe.

branding.on_end_url

string, optional

If set, the agent will be redirected to this url after the Session ends. If not set, the window will be attempted to be closed. Defaults to null.

branding.retry_url

string, optional

If set, the visitor will be able to click a "Retry now" link that redirects to this url if there are problems. When null, no button is displayed. Defaults to null.

initial_notes

string, optional

The starting state of the Agent notes for the Session. You can use this to add a template of what they should fill out.

metadata

Record<string, string>, optional

A JSON-encodeable object of metadata to add to the Session object. This can be used when retrieving a list of Sessions to run your own analytics. The object should be flat, meaning values can only be strings, numbers, or booleans.

permissions.allow_agent_redirect

boolean

Whether the agent should have access to remote agent redirect & reload features (defaults to true, unless disabled through the Javascript SDK).

permissions.allow_audio

boolean

Whether the agent should have access to audio (defaults to true, unless disabled through the Javascript SDK).

permissions.allow_click

boolean

Whether the agent should have access to remote click (defaults to true, unless disabled through the Javascript SDK).

permissions.allow_console

boolean

Whether the agent should have access to remote console capabilities (defaults to false).

permissions.allow_draw

boolean

Whether the agent should have access to drawing (defaults to true, unless disabled through the Javascript SDK).

permissions.allow_scroll

boolean

Whether the agent should have access to remote scroll (defaults to true, unless disabled through the Javascript SDK).

permissions.allow_type

boolean

Whether the agent should have access to remote type (defaults to true, unless disabled through the Javascript SDK).

permissions.allow_confetti

boolean

Whether the agent should have access to throw confetti (defaults to true).

permissions.allow_notes

boolean

Whether the agent should be able to leave notes (defaults to true).

permissions.allow_show_agent_screen

boolean

Whether the agent should be able to share their screen to the Visitor (defaults to true).

permissions.allow_request_visitor_screen

boolean

Whether the agent should be able to ask the Visitor to share their full screen (defaults to true).

permissions.hide_private_details

boolean

Whether the Visitor private information (such as IP address) should be hidden from the Agent (defaults to false).

language

string

The language to use for the interface. Defaults to the user's browser.

viewer.id

string, optional

The ID of the person viewing the screen (in case this is not the Agent).

viewer.name

string, optional

The name of the person viewing the screen (in case this is not the Agent).

webhook_url

string, url, optional

After the session is ended, a POST request will be made to this URL, sending the Session data as JSON.

Response

HTTP 200
{
    "status": "ok",
    "watch_url": "https://cobrowsingapi.com/session/a964e00a-c685-4d54-98d4-ea0bcb154d57",
    "expiration": "2022-01-11T18:01:49.700Z"
}

Field

Type

Description

expiration

Datetime (ISO 8601)

Time at which the link is no longer valid.

watch_url

string

The Secure watch url.

Errors

Code

Description

404

The Visitor does not exist.

402

This Session would put you over your subscription limits.

Stopping an active Session

Use this endpoint to stop an active Session.

Request

DELETE https://api.upscope.io/v1.3/visitors/{visitor_id}/session

Parameter

Type

Description

{visitor_id}

string

The short id of the Visitor.

Response

// HTTP 200
{
  "status": "ok"
}

Errors

Code

Description

404

The Visitor does not exist.

Deleting a Visitor from Upscope

Use this endpoint to delete a Visitor from Upscope entirely.

You can only delete Visitors who are not currently online.

DELETE https://api.upscope.io/v1.3/visitors/{visitor_id}

Parameter

Type

Description

{visitor_id}

string

The short id of the Visitor.

Response

// HTTP 200
{
  "status": "ok"
}

Errors

Code

Description

404

The Visitor does not exist.

409

The Visitor is online.

Deleting all visitor from Upscope

Use this endpoint to delete all Visitors from your Upscope account.

This will delete only Visitors that are offline.

Request

DELETE https://api.upscope.io/v1.3/visitors?all=true

Parameter

Type

Description

all

boolean

Set to true to confirm deleting all Visitors.

Response

// HTTP 200
{
  "status": "ok"
}

Agent Lookup

Use this endpoint to lookup an agent from your Upscope account.

You must send either the email or the external_id

Using the email it will lookup for users from your account, while using the external_id it will lookup for external agents from your account.
If you use any other parameter rather than email or external_id it will return not found.

Request

GET https://api.upscope.io/v1.3/agents/lookup?email=john@acme.com

Parameter

Type

Description

email

string (Only specify email or external_id)

The Agent email, this will return a HelloScreen or UserView user.

external_id

string (Only specify email or external_id)

The External Agent id, this will return a Co-Browsing API Agent.

Response

// HTTP 200
{
  "agent": {
    "id": "u_1234",
    // ... Agent data
  },
  "status": "ok"
}

Field

Type

Description

agent

Agent

The Agent who started or joined the Session as an observer

agent.sessions

Session[]

The list of the agent's last 10 sessions.

Errors

Code

Description

404

Agent not found

Retrieving a list of Sessions

Use this endpoint to retrieve a list of Sessions.

Request

GET https://api.upscope.io/v1.3/cobrowsing_sessions/list

Parameter

Type

Description

before_id

string, optional

Only list Sessions that happened before the Session with the specified id (used for pagination)

after_id

string, optional

Only list Sessions that happened before the Session with the specified id (used for pagination)

ongoing_only

boolean (defaults to false)

Only list Sessions that are currently active.

updated_after

Datetime, optional

Only list Sessions that have had some sort of update to their record after this time.

Response

// HTTP 200
{
    "status": "ok",
    "cobrowsing_sessions": [
      {
        id: "s_123",
		// ... Session details
      }
	],
    "has_more": true,
    "last_id": "s_456"
}

Field

Type

Description

cobrowsing_sessions

Session[]

A list of Sessions, sorted by start date, from first to last.

has_more

boolean

Whether there are more Sessions matching your filter. (If so, paginate by changing the after_id)

last_id

string | null

The id of the last Session. This is always the same as the last Session from the array, and can be used as a cursor with after_id)

Authorizing an on-premise Session

Use this endpoint to authorize an on-premise Session.

Using our Dashboard?

If you have integrated your on-premise version of Upscope to our dashboard, you don't need to use the API. It all just works.

Request

// POST https://api.upscope.io/v1.3/onpremise/token
{
  "visitor_id": "VISITOR123",
  "agent": {
    "id": "123",
    "name": "Joe Smith"
  }
}

Parameter

Type

Description

agent.id

string

The ID of the Agent (required).

agent.name

string

The name of the Agent (required).

visitor_id

string

The ID of the Visitor you want to co-browse with.

Response

// HTTP 200
{
    "authorized": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkw...."
}

Field

Type

Description

authorized

boolean

true to indicate the Session was authorized.

token

string

The token to send to the on-premise version of Upscope.

Errors

Code

Description

402

This session was not authorized.