Skip to content

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: string 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 accept1
active — Session has started
snapshotReceived — First frame received
viewerReadyThe 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: string 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.