Co-Browsing API

    Documentation

    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 should ideally be opened in an iframe you control. This setup allows you 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"></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);
});

    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" Provides 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.