REST API (on premise)

On-Premise REST API Overview

The on-premise REST API functions similarly to the cloud version, with some differences detailed below.

Enabling the API

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

Authentication

To authenticate your requests to the REST API, add an Authorization header set to the value you provided in the REST_KEY environment variable.

The Visitor Object

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

Endpoints

On-premise, the REST API is mounted on the /api path of your base endpoint. For example, if your BASE_ENDPOINT is https://support.acmetech.com/cobrowsing, one of the endpoints will be 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 search for Visitors.

GET /visitors/list/search

Parameter	Type	Description
q	string, optional	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 retrieve a specific Visitor.

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, 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, optional	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. Defaults to false. Can be set to page_only to remove everything, including the Agent's UI.
branding.on_end_url	string | null, optional	If set, the agent will be redirected to this URL after the Session ends. Defaults to null.
branding.retry_url	string | null, optional	If set, the visitor can click a "Retry now" link that redirects to this URL if there are problems. Defaults to null.
permissions.allow_agent_redirect	boolean, optional	Whether the agent should have access to remote agent redirect & reload features (defaults to true).
permissions.allow_click	boolean, optional	Whether the agent should have access to remote click (defaults to true).
permissions.allow_console	boolean, optional	Whether the agent should have access to remote console capabilities (defaults to false).
permissions.allow_draw	boolean, optional	Whether the agent should have access to drawing (defaults to true).
permissions.allow_scroll	boolean, optional	Whether the agent should have access to remote scroll (defaults to true).
permissions.allow_type	boolean, optional	Whether the agent should have access to remote type (defaults to true).
permissions.allow_show_agent_screen	boolean, optional	Whether the agent should be able to share their screen with the Visitor (defaults to true).
permissions.allow_request_visitor_screen	boolean, optional	Whether the agent should be able to ask the Visitor to share their full screen (defaults to true).
permissions.hide_private_details	boolean, optional	Whether the Visitor's private information (such as IP address) should be hidden from the Agent (defaults to false).
viewer.id	string, optional	The ID of the person viewing the screen (if not the Agent).
viewer.name	string, optional	The name of the person viewing the screen (if not the Agent).

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.