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 Co-Browsing API 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 Co-Browsing API event
console.log('Co-Browsing API event type', data.type);
});
If you have embedded Co-Browsing API within your application like this:
<iframe src="https://acmechat.com/cobrowse?id=VISITOR123" id="upscope-iframe"></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" | 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" | null | Sets which mode the Agent is currently using. Allowed values are: draw — Drawing mode; pointer — Pointer (spotlight) mode; cursor — Cursor mode; null — No tool selected. |
switchColor | color: string? | Changes the current Agent color. If color is not set, it will toggle between built-in colors. |