Skip to content

REST API (on premise)

The on-premise REST API works pretty similarly to the cloud one. There are some changes however, which we'll detail below.

Enabling the API

By default, the API is disabled. It will only be enabled when you add a REST_KEY env var.

Authentication

To authenticate your requests to the REST API, you'll need to add a Authorization header set to the value you provided in the REST_KEY env var.

The Visitor object

The Visitor object will be potentially slightly different in the on-premise version depending on your configuration. Most of the attributes will be present and all Visitors will have the same properties.

Endpoints

On premise, the REST API will be mounted on the /api path of your base endpoint.

If your BASE_ENDPOINT is https://support.acmetech.com/cobrowsing, one of the endpoints will be for instance https://support.acmetech.com/cobrowsing/api/visitors/list/latest.

Listing the latest Visitors

Use this endpoint to list the latest online Visitors. This only works with MongoDB.

GET /visitors/list/latest

Response

HTTP 200

{
  "status": "ok",
  "visitors": [
    {
      "short_id": "1234",
      // ...
    }
  ]
}
Field Type Description
visitors Visitor[] List of Visitors matching the query.

Searching for a Visitor

Use this endpoint to list the latest online Visitors.

GET /visitors/list/search
Parameter Type Description
q String? The search query in this format. If left empty, the latest Visitors will be returned.

Response

HTTP 200

{
  "status": "ok",
  "visitors": [
    {
      "short_id": "1234",
      // ...
    }
  ]
}
Field Type Description
visitors Visitor[] List of Visitors matching the query.

Retrieving a Visitor

Use this endpoint to list the latest online Visitors.

GET /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.

Starting a Session

To start a Session with one of your Visitors, you'll need to first obtain an authorization token from our server, then make a request to your on-premise REST API.

POST /visitors/{visitor_id}/watch_url

{
  "licenseToken": "token1234",
  "branding": {
    "naked": true,
  },
  "permissions": {},
  "agent": {
    "id": "123",
    "name": "Joe Smith"
  },
  "metadata": {}
}
Parameter Type Description
{visitor_id} String The short id of the Visitor.
licenseToken String The token obtained from here.
agent.id String The ID of the Agent (required).
agent.name String The name of the Agent (required).
branding.naked false, true, 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 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 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.
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).

Response

HTTP 200

{
    "status": "ok",
    "watch_url": "https://support.acmetech.com/cobrowsing/screen?id=jfoiajsdoif&token=osdjfoijo"
}
Field Type Description
watch_url String The Secure watch url.