REST API

Embedded Session Control

When you generate a Secure watch link through the REST API, you have the option of setting the branding.naked parameter to "page_only", which means no UI is shown to the Agent.

The generated link would ideally be opened in an iframe you control, and this gives you the ability to listen for events and control the Session by sending and receiving messages to the iframe.

Communicating with the iframe

To listen for updates to the Session status, add an event listener to the iframe's parent frame (i.e. your page) and filter messages that come from the iframe.

You can post Messages to the iframe's window to control the Session.

If you have embedded Upscope within your application like this:

<iframe src="https://acmechat.com/cobrowse?id=VISITOR123" id="upscope-iframe"/>

You can start listening for events by doing:

const upscopeWindow = document.getElementById('upscope-iframe').contentWindow;
window.addEventListener('message', event => {
  if (!event.source || event.source !== upscopeWindow)
    return;
  const {data} = event;
  // ... deal with the Upscope event
  console.log('Upscope event type',data.type);
});

If you have embedded Upscope within your application like this:

<iframe src="https://acmechat.com/cobrowse?id=VISITOR123" id="upscope-iframe"/>

You can send instructions by doing:

const upscopeWindow = document.getElementById('upscope-iframe').contentWindow;
upscopeWindow.postMessage({
  action: "name",
  // ... other parameters
}, '*');

Events

Events will be received in this format:

{
  "type": "eventType",
  // ...parameters
}

The following events are sent by the iframe to the parent frame.

Type	Parameters	Description
`sessionStatusUpdate`	`sessionStatus: "waiting" \| "pendingRequest" \| "active" \| "snapshotReceived" \| "viewerReady" \| "terminated"`	Gives updates about the status of the Session. `sessionStatus` will be one of: `waiting` — waiting for the browser to respond `pendingRequest`— waiting for the Visitor to accept `active` — Session has started `snapshotReceived` — First frame received `viewerReady` — The page is visible `terminated` — The session has ended
`currentColor`	`color: string`	Informs the parent of the current active color for the Agent tools.

Instructions

Instructions need to be sent in this format:

{
  "action": "actionName",
  // ... parameters
}

The following instructions are available.

Action	Parameters	Description
`endSession`	—	Terminates the Session.
`setMode`	`mode: "draw" \| "pointer" \| "cursor"`	Sets which mode the Agent is currently using. Allowed values are: `draw` — Drawing mode `pointer` — Pointer (spotlight) mode `cursor` — Cursor mode
`switchColor`	`color: string?`	Changes the current Agent color. If `color` is not set, it will toggle between built in colors.