Object Types
Visitor
A Visitor represents a person connected through the Co-Browsing API SDK who is available to co-browse with.
Attributes
| Attribute name | Type | Description |
|---|---|---|
added_at | Datetime (ISO 8601) | The first time the Visitor was seen. |
api_key | string | Your public API key. |
browser_name | string | null | The name of the browser used by the Visitor (e.g. Mobile Safari). Always null for non-web SDKs. |
call_name | string | null | The call identification (used for the Agent's personal link). |
device_name | string | null | The name or brand of the device (e.g. iPhone). Always null for non-web SDKs. |
device_type | string | null | The category of device the Visitor is connecting from. It will be one of desktop, console, mobile, tablet, smarttv, wearable, embedded. Always null for non-web SDKs. |
email | string | null | The Visitor's email. |
identities | string[] | A list of strings used to identify the Visitor. |
integration | string | null | The auto integration we have performed on this Visitor. This will be set to the live chat system you have installed on the page last visited by the Visitor. |
ip_address | string | The IP address the Visitor last connected from. |
is_in_session | boolean | A boolean describing whether the Visitor is currently screen sharing with someone. |
is_online | boolean | A boolean describing whether the Visitor is currently connected to Co-Browsing API (and available for screensharing). |
is_supported | boolean | A boolean describing whether the Visitor's browser supports Co-Browsing API. |
is_waiting_for_call | boolean | A boolean describing if the Visitor is waiting for a call from the agent. |
js_configuration | boolean | A boolean describing whether the Visitor has configured Co-Browsing API through the Javascript API in a way that could conflict with the account's general settings. This is also set to true if configured through mobile SDKs public APIs. |
last_seen_at | Datetime (ISO 8601) | A timestamp of the last time the Visitor was seen on the website. |
last_url | string | null (Only for web SDK) | The last URL the Visitor has visited. |
location_city | string | null | The city the Visitor is in (according to their IP address). If the city is not known, this will be null. |
location_country_name | string | null | The country (name) the Visitor is in (according to their IP address). If the country is not known, this will be null. |
location_country | string | null | The country (code) the Visitor is in (according to their IP address). If the country is not known, this will be null. |
lookup_code | string | null | The code your agent can search for to quickly find the Visitor in the interface. If not set, it will be null. |
name | string | null | It will return the first item from identities that looks like a name. |
nickname | string | It will return the Visitor's name, the first part of the Visitor's email, or the Visitor's ID. |
short_id | string | The Co-Browsing API ID of the Visitor. |
tags | string[] | The value provided in the tags. |
unique_id | string | null | The unique ID used to identify the Visitor. If this was not set, it will be null. |
watch_link | string | A public URL used to start a session with the Visitor. |
sdk | string | Either web, ios or android. |
Session
A Session is a co-browsing interaction between one or more Agents and a Visitor.
Call vs Session
Throughout the docs, you'll see the concept of Calls and Sessions. Sessions can happen with or without Calls, which are the audio component of a Session.
Attributes
| Attribute name | Type | Description |
|---|---|---|
agents | Agent[] | The collection of agents that joined the Session. |
agent_notes | Array<{text: string, by: string}> | The notes taken by the agents. by will be the id of the agent. |
call_length_seconds | integer | The duration of the audio call in seconds. |
call_name | string | null | The username of the Agent that initiated the Session through their personal link. |
ended_at | Datetime (ISO 8601) | The datetime of when the Session ended. |
features_used | string[] | The collection of features used (e.g ["remote_typing"]). |
formatted_call_length | string | The duration of the audio call formatted (e.g "00:11"). |
formatted_length | string | The duration of the Session formatted (e.g "01:10"). |
metadata | Record | Metadata from the Session creation, plus the metadata from the Visitor object with the keys prefixed with visitor_. |
quality_feedback | Array<{rating: number, feedback: string | null, by: string}> | The feedback by the Visitor and the Agents on the quality of the Session. by will be the id of the agent. |
visitor_agent_feedback | string | null | The rating feedback by the Visitor for the Agent. This is only present if there is a single Agent. |
visitor_agent_rating | number | null | The rating left by the Visitor for the Agent. This is only present if there is a single Agent. |
visitor_email | string | null | The email for the Visitor. |
visitor_ip_address | string | null | The IP address for the Visitor (always present unless the Visitor data has been deleted). |
visitor_unique_id | string | null | The unique ID for the Visitor. |
id | string | The ID of the Session. |
length_seconds | integer | The duration of the Session in seconds. |
on_premise | boolean | A boolean describing whether the Session happened on an on-premise version of Co-Browsing API. |
public_video_url | string | null | A public URL for the recording of the Session, if one is available, which requires the viewer to be authenticated into Co-Browsing API. |
secret_video_url | string | null | A secret URL pointing directly to the video recording of the Session, if one is available. |
session_authorized | boolean | A boolean describing whether the Session was authorized by the Visitor. |
source | string | null | A number describing the source of the Session. One of: api, search, lookup code, personal link, agent request, integration. |
start_url | string | null (will be null for mobile SDKs) | The URL the Visitor was at when the session started. |
started_at | Datetime (ISO 8601) | The datetime of when the Session started. |
video_status | string | null (will be null if video recording is not enabled) | The status of the Session's video recording. One of pending, recording, not_available, ready, expired, removed. |
visitor_id | string | The ID of the Visitor. |
went_live | boolean | A boolean describing whether the Session actually started. |
Connection
A Connection represents a single active visitor connection — for example, an open browser tab or a mobile app instance. A visitor can have more than one connection at a time. Connection objects are camelCase and are only available in the embedded session state.
Attributes
| Attribute name | Type | Description |
|---|---|---|
uniqueConnectionId | string | Unique ID for this connection. Used with the setActiveConnection instruction to switch to it. |
currentUrl | string | null | The URL currently open in this connection. |
activeSince | string (ISO 8601) | When this connection became active. |
status | "active" | "disconnected" | Whether this connection is currently active. |
expectedDisconnect | { returnTimeSeconds: number | null; message: string | null; title: string | null; ts: number } | null | If set, the visitor is expected to disconnect temporarily (e.g. navigating to another page). returnTimeSeconds is how long until they return, or null if unknown. |
hasFocus | boolean | Whether this connection's tab or window currently has focus. |
lastFocusAt | Date | null | When this connection last had focus. |
screenWidth | number | Screen width in pixels. |
screenHeight | number | Screen height in pixels. |
audioSupported | boolean | Whether this connection supports audio. |
fullTabStatus | "off" | "authorizing" | "active" | The current full-tab sharing state for this connection. |
requireAuthorizationForSession | boolean | Whether the visitor must authorize before the session can start. |
requireControlRequest | boolean | Whether the agent must request control before interacting. |
allowRemoteConsole | boolean | Whether the agent can run console commands. |
allowAgentRedirect | boolean | Whether the agent can redirect the visitor's browser. |
allowRemoteClick | boolean | Whether the agent can click on the visitor's screen. |
allowRemoteScroll | boolean | Whether the agent can scroll on the visitor's screen. |
allowRemoteType | boolean | Whether the agent can type on the visitor's screen. |
allowFullScreen | boolean | Whether full-screen sharing is allowed. |
allowRequestFullTab | boolean | Whether full-tab sharing is allowed. |
cobrowsingVideoEnabled | "two_way" | "visitor_to_agent" | "agent_to_visitor" | "disabled" | The video sharing configuration for this connection. |
cobrowsingVideoAudioRelationship | "independent" | "video_requires_audio" | "automatic" | How audio and video relate to each other. video_requires_audio — video can only be enabled when audio is active; automatic — audio starts automatically with video. |
enableSessionRating | boolean | Whether the visitor is prompted to rate the session. |
agentPrompt | string | null | A custom message shown to the agent at the start of the session. |
assetsProxyConfigured | boolean | Whether an assets proxy is configured for this connection. |
Agent
An Agent is someone who started or joined the Session as an observer.
Attributes
| Attribute name | Type | Description |
|---|---|---|
agent_nickname | string | The Agent's nickname. |
email | string | null | The Agent's email (always null for Co-Browsing API agents, always present otherwise). |
external_id | string | null | If generated through the REST API, the ID provided by you (always null for HelloScreen or UserView users, always present otherwise). |
id | string | The Agent's id within Co-Browsing API (u_${string} for HelloScreen or UserView users or ea_${string} for Co-Browsing API agents). |
name | string | The Agent's name. |
on_premise | boolean | A boolean describing whether the agent is on premise. |