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 |
|---|---|---|
upscope.sessionState.update | state: EmbeddedSessionState | Fired whenever the session state changes. Contains a full snapshot — see Session State below. This is the primary event to listen for. |
sessionEnded | reason: "ended" | "error" | Fired when the session is terminated. ended — session ended normally; error — session ended due to an error (see the error event for details). |
customMessage | message: Record<string, unknown> | Fired when the visitor's SDK sends a custom message via Upscope('sendCustomMessage', ...). |
error | error: string | Fired when a connection or remote control error occurs. Possible values: connection:authentication, connection:data, connection:user_not_found, connection:user_not_online, connection:expired, connection:version_not_supported, remote_control:inactive, remote_control:element_not_allowed, remote_control:click_not_allowed, remote_control:type_not_allowed, remote_control:scroll_not_allowed. |
Session State
Every upscope.sessionState.update event carries an EmbeddedSessionState object — a full snapshot of everything happening in the session at that moment.
| Property | Type | Description |
|---|---|---|
activeConnectionId | string | undefined | The ID of the visitor connection currently being viewed. A visitor can have multiple connections (e.g. multiple open tabs). Use setActiveConnection to switch between them. |
agentIdleness | "active" | "willDisconnect" | "disconnected" | The activity state of the agent. willDisconnect — the agent will disconnect shortly due to inactivity. |
audioState | "off" | "ringing" | "accepted" | "authorizing" | "active" | The current audio call state. |
availableModes | ("visitor_browser" | "visitor_screen" | "agent_screen")[] | The sharing modes available in the current session. |
color | string | The current active color for the agent drawing and pointer tools. |
connected | boolean | Whether the session is currently connected. |
connections | Connection[] | All active visitor connections (browser tabs or app instances). Use alongside activeConnectionId to let the agent switch between them. |
controlTool | "cursor" | "drawing" | "pointer" | null | The currently active agent control tool, or null if none is selected. |
currentUrl | string | null | The current URL of the active visitor connection. |
dataBounceSpeed | number | Round-trip data latency in milliseconds. Values above 500ms indicate a slow connection. |
isVideoOn | boolean | Whether video streaming is currently active. |
mode | "visitor_browser" | "visitor_screen" | "agent_screen" | "other_agent_screen" | undefined | The current sharing mode. visitor_browser — viewing the visitor's browser tab; visitor_screen — viewing the visitor's full screen; agent_screen — this agent is sharing their screen; other_agent_screen — another agent is sharing their screen; undefined — session has not started. |
muted | boolean | Whether the agent's audio is muted. |
observersCount | number | The number of agents currently observing the session. |
sessionStatus | "waiting" | "pendingRequest" | "active" | "snapshotReceived" | "viewerReady" | "terminated" | The current session status. 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. |
size | { width: number; height: number } | undefined | The current dimensions of the viewer in pixels. |
videoAgentState | "off" | "authorizing:<observerId>" | "active:<observerId>" | Video state from the agent side. The suffix after : is the observer ID. |
videoVisitorState | "off" | "ringing" | "authorizing:<connectionId>" | "active:<connectionId>" | Video state from the visitor side. ringing — incoming video call; the suffix after : is the visitor's connection ID. |
viewerAudioAvailable | boolean | Whether audio is available on the agent side. |
visitor | Visitor? | The visitor in the session. Property names use camelCase rather than snake_case. undefined if the session has not started. |
visitorAudioAvailable | boolean | Whether audio is available on the visitor's side. |
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. |
toggleAudio | on: boolean | Toggles the audio state. |
toggleVideo | — | Toggles the video state. |
setMuted | muted: boolean | Sets the muted state for audio. |
beginVideo | — | Begins video streaming. |
endVideo | — | Ends video streaming. |
forceRefresh | — | Forces a refresh of the session. |
historyBack | — | Navigates back in the session history. |
historyForward | — | Navigates forward in the session history. |
reloadPage | — | Reloads the current page in the session. |
requestControl | — | Requests control of the session. |
requestFullTab | — | Requests full tab control. |
runConsoleCommand | command: string | Runs a console command in the session. |
sendCustomMessage | message: Record<string, unknown> | Sends a custom message to the session. |
setActiveConnection | connectionId: string | Switches the active visitor connection (e.g. to a different browser tab). Use activeConnectionId and connections from EmbeddedSessionState to get available connection IDs. |
setCurrentUrl | url: string | Sets the current URL in the session. |
stopFullTab | — | Stops full tab control. |
emojiConfetti | emoji: string | Triggers an emoji confetti effect using the specified emoji. |