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. |
Generating a Link to Start Screen Sharing with a Visitor
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. |