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).
`viewer.id`	String	The ID of the person viewing the screen (in case this is not the Agent).
`viewer.name`	String	The name of the person viewing the screen (in case this is 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.