Loading...

On Premise

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.