API Reference
Agent SDK API reference
The Cobrowse Agent SDK provides a way to interact with the Cobrowse APIs for a variety of use cases. Primarily this library is designed for building a fully white-labeled version of Cobrowse, including custom user interfaces and styling to match your own platform.
The library can be used either from the browser (most common), or a NodeJS environment. Note: not all APIs are available when used in NodeJS.
EventEmitter
↳default
• new default(
token?
, options?
)Create a new Agent SDK instance. An instance encapsulates information about your API location (if using the self-hosted Cobrowse Enterprise option), and optionally, the authorization token for the agent using the SDK.
Options
api
- The url for an Enterprise Cobrowse instance. You do not need to configure this when using our global hosted service.const token = await myJWTGeneratingFunction()
const cobrowse = new CobrowseAPI(token, { api: 'https://cobrowse.example.com' })
Parameters
Name | Type | Description |
---|---|---|
token? | string | |
options? | Record <string , any > | Options for configuring this instance of CobrowseAPI. |
Overrides
EventEmitter.constructor
•
get
api(): string
The url for the Cobrowse instance.
Returns
string
•
get
devices(): DevicesAPI
Namespace API for devices. A device in Cobrowse is how a single instance of an app or website is tracked by Cobrowse.
Returns
DevicesAPI
•
get
license(): string
The license key for the Cobrowse account. This uniquely identifies your account within Cobrowse, you may choose to have different license keys for development, test, and production environments.
Returns
string
•
set
license(license
): void
The license key for the Cobrowse account. This uniquely identifies your account within Cobrowse, you may choose to have different license keys for development, test, and production environments.
Parameters
Name | Type |
---|---|
license | string |
Returns
void
•
get
recordings(): SessionRecordingAPI
Namespace API for recordings. A recording in Cobrowse represents the video and event metadata for a recorded session.
Returns
SessionRecordingAPI
•
get
sessions(): SessionsAPI
Namespace API for sessions. A session in Cobrowse represents a single screensharing activity with an agent.
Returns
SessionsAPI
•
get
token(): string
The JWT for API authorization. This token should be securely generated by your backend to authorize use of the Cobrowse APIs.
Returns
string
•
set
token(token
): void
The JWT for API authorization. This token should be securely generated by your backend to authorize use of the Cobrowse APIs.
Parameters
Name | Type |
---|---|
token | string |
Returns
void
•
get
users(): UsersAPI
Namespace API for users.
Returns
UsersAPI
▸ attachContext(
target
): Promise
<RemoteContext
>Attach the agent context to an iframe; no JWT is required to use these APIs. The returned context allows you to control certain elements within the iframe hosting the screenshare. For example, you may switch the active agent tool being used, change the session into a "full device" mode session, or just subscribe to changes in the session parameters.
const cobrowse = new CobrowseAPI()
const frameEl = document.getElementById('myIframe')
const ctx = await cobrowse.attachContext(frameEl)
ctx.on('session.updated', (session) => {
console.log('session was updated', session)
})
Parameters
Name | Type | Description |
---|---|---|
target | HTMLIFrameElement | An iframe element. |
Returns
Promise
<RemoteContext
>- The context returns contains methods specific to controlling the iframe
Represents a device in Cobrowse. A device in Cobrowse is how a single instance of an app or website is tracked by Cobrowse. Each website within each different browser on a user's machine will be tracked as a separate device. Devices can be listed and filtered by support agents to find a specific user's device. Read more about Identifying your devices to add metadata for filtering.
const cobrowse = new CobrowseAPI(...)
const device = await cobrowse.device.get('some device id here')
device.subscribe()
device.on('updated', d => console.log('device was updated', d))
fires
updated - The updated event will be fired when device data changes.EventEmitter
↳Device
• connectable:
boolean
Is the device in a state where it can accept a screenshare connection
• custom_data:
Record
<string
, any
>The metadata you have associated with this device for discoverability and filtering by agents
• device:
DeviceInfo
The device metadata exposed by the Cobrowse SDKs
• id:
string
The unique ID of this device, generated internally by the Cobrowse SDKs. You cannot control this value.
• last_active:
Date
The last time the device was seen
• online:
boolean
Is the device currently connected to the Cobrowse service
▸ on(
event
, listener
): Device
Listen for events on this device.
Parameters
Name | Type |
---|---|
event | string |
listener | ( device : Device ) => void |
Returns
Device
Overrides
EventEmitter.on
▸ subscribe():
Promise
<void
>Subscribe to changes in this device. Note: this is a browser only method and will not work from a NodeJS environment
Returns
Promise
<void
>
▸ toJSON():
Device
Converts this device instance to a plain object.
Returns
Device
▸ unsubscribe():
void
Unsubscribe from this device. Note: this is a browser only method and will not work from a NodeJS environment
Returns
void
• app_id:
string
An identifier for the app being used (e.g. the domain name, or iOS app ID).
• app_name:
string
The name of the app being used by the end user.
• device:
string
The type of the device being used, e.g. iPhone or Chrome Browser.
• device_locale:
string
The preferred locale of the user's device.
• device_timezone:
string
The timezone of the user's device.
• full_device_control:
boolean
(Android only) Indicates whether full device remote control is currently available
• os_version:
string
The OS version of the device.
• platform:
string
Which platform is being used, e.g. web, ios, android, windows, macos
• sdk_version:
string
The version of the Cobrowse SDK that the device is running
▸ get(
id
, query?
): Promise
<Device
>Get a device by ID.
const cobrowse = new CobrowseAPI(...)
const device = await cobrowse.devices.get('some device id here')
Parameters
Name | Type |
---|---|
id | string |
query? | Record <string , string > |
Returns
Promise
<Device
>
▸ list(
query?
): Promise
<Device
[]>List devices, optionally filter by query parameters.
Supported query parameters:
filter_XXX
- where XXX is replaced by your customData field names. e.g. filter_user_id=abc would filter devices with customData = { user_id: 'abc' }
seen_before
- only include devices that checked-in with the Cobrowse service before this dateseen_after
- only include devices that checked-in with the Cobrowse service after this dateconst cobrowse = new CobrowseAPI(...)
const devices = await cobrowse.devices.list({ filter_user_id: 'abcdef' } })
Parameters
Name | Type |
---|---|
query? | Record <string , string > |
Returns
Promise
<Device
[]>Control Cobrowse hosted in an iframe from a parent context. Note: these are browser only methods and will not work from a NodeJS environment
fires
session.updated - This event is fired when a property of the session is changed, for example full_device mode is switched on of off.fires
screen.updated - This event is triggered when some metadata about the screen changes, for example the size or orientation. Note, this event is only available via the RemoteContext.fires
error - This event is triggered when an error happens in the iframe (e.g. a license limit is hit)EventEmitter
↳RemoteContext
▸ androidBack():
Promise
<boolean
>Triggers the Android Back button
const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.androidBack()
Returns
Promise
<boolean
>
▸ androidHome():
Promise
<boolean
>Triggers the Android Home button
const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.androidHome()
Returns
Promise
<boolean
>
▸ clearAnnotations():
Promise
<boolean
>Clear all agent session annotations from the user's view.
const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.clearAnnotations()
Returns
Promise
<boolean
>
▸ destroy():
void
Destroy this remote context; stops listening for events and detaches from the iframe.
const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.destroy()
Returns
void
▸ endSession():
Promise
<boolean
>End the current agent session.
const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.endSession()
Returns
Promise
<boolean
>
▸ on(
event
, listener
): RemoteContext
Listen for events in this context.
Parameters
Name | Type |
---|---|
event | string |
listener | ( param : any ) => void |
Returns
RemoteContext
Overrides
EventEmitter.on
▸ setFullDevice(
state
): Promise
<boolean
>Set the current state of the session full-device mode. A full device session enables the agent to capture all screens of the user's device, not just those inside your app or website. Initiates request or ends full-device mode. The user must approve when switching to full device mode.
const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.setFullDevice('requested')
Parameters
Name | Type |
---|---|
state | "off" | "requested" |
Returns
Promise
<boolean
>
▸ setRemoteControl(
state
): Promise
<boolean
>Set the current state of remote control, allowing the agent to request remote control of the user's device. Initiate or end remote control. Note: The agent may not set the remote control state to
on
directly, they can only set it to requested
and the user must approve if required.const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.setRemoteControl('requested')
Parameters
Name | Type |
---|---|
state | "off" | "requested" | "on" | "rejected" |
Returns
Promise
<boolean
>
▸ setTool(
tool
): Promise
<boolean
>Set the tool to use in the Agent session.
const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.setTool('drawing')
Parameters
Name | Type |
---|---|
tool | "laser" | "drawing" | "control" |
Returns
Promise
<boolean
>Represents a session in Cobrowse.
fires
updated - fired when a session property changesfires
ended - fired when a session transitions to the ended
stateEventEmitter
↳Session
• activated:
Date
The activation timestamp of the session. This is the time the user accepted the session.
• agent:
Object
Metadata about the agent that started the session
Type declaration
Name | Type |
---|---|
colour | string |
id | string |
name | string |
• code:
string
A 6 digit, human friendly code that can be used to initiate a session
• created:
Date
The date the session was first created (this will usually be before the
activated
timestamp).
• custom_data:
Record
<string
, any
>The metadata you have associated with this session for discoverability and filtering by agents.
• device:
DeviceInfo
Metadata about the user's device
• ended:
Date
The timestamp the session was ended
• full_device:
"off"
| "requested"
| "on"
| "rejected"
The state of the full device mode
• id:
string
The unique ID for this screenshare session
• recorded:
boolean
Was the session recorded
• remote_control:
"off"
| "requested"
| "on"
| "rejected"
The state of the remote control authorization for the session
• state:
"pending"
| "authorizing"
| "active"
| "ended"
The current state of the session. A session will progress through its lifecycle in this order:
pending
→ (authorizing
→) active
→ ended
. Only session that require user consent will enter the authorizing
state.
• updated:
Date
The timestamp of the last update to the session
▸ end():
Promise
<void
>Ends this session.
Returns
Promise
<void
>
▸ isActive():
boolean
True if the session is active. An active session is one where the user has accepted the screen share if required and frame are streaming to the agent
Returns
boolean
▸ isAuthorizing():
boolean
True if the session is authorizing. An authorizing session is one where the user has been presented with a consent dialog but has not yet agreed.
Returns
boolean
▸ isEnded():
boolean
True if the session is ended.
Returns
boolean
▸ isPending():
boolean
True if the session is pending. A pending session is the inital state, waiting for either a device or agent to join
Returns
boolean
▸ on(
event
, listener
): Session
Listen for events on this session.
Parameters
Name | Type |
---|---|
event | "ended" |
listener | ( session : Session ) => void |
Returns
Session
Overrides
EventEmitter.on
▸ on(
event
, listener
): Session
Parameters
Name | Type |
---|---|
event | "updated" |
listener | ( session : Session ) => void |
Returns
Session
Overrides
EventEmitter.on
▸ setFullDevice(
state
): Promise
<boolean
>Set the current state of the session full-device mode. A full device session enables the agent to capture all screens of the user's device, not just those inside your app or website. Initiates request or ends full-device mode. The user must approve when switching to full device mode.
Parameters
Name | Type |
---|---|
state | "off" | "requested" |
Returns
Promise
<boolean
>
▸ setRemoteControl(
state
): Promise
<void
>Set the current state of remote control, allowing the agent to request remote control of the user's device. Initiate or end remote control. Note: The agent may not set the remote control state to
on
directly, they can only set it to requested
and the user must approve if required.Parameters
Name | Type |
---|---|
state | "off" | "requested" | "on" | "rejected" |
Returns
Promise
<void
>
▸ subscribe():
Promise
<void
>Subscribe to changes in this session. Note: this is a browser only method and will not work from a NodeJS environment
Returns
Promise
<void
>
▸ toJSON():
Session
Converts this session instance to a plain object.
Returns
Session
▸ unsubscribe():
void
Unsubscribe from this session. Note: this is a browser only method and will not work from a NodeJS environment
Returns
void
Represents a session recording in Cobrowse.
EventEmitter
↳SessionRecording
• id:
string
The unique ID for this recording
• video:
Object
Provides access to the video for this recording
Type declaration
Name | Type |
---|---|
fetch | () => Promise <any > |
url | () => Promise <string > |
▸ destroy():
Promise
<any
>Deletes this recording from the server
Returns
Promise
<any
>
▸ events():
Promise
<any
[]>Gets the list of events for this recording
Returns
Promise
<any
[]>
▸ toJSON():
SessionRecording
Converts this session instance to a plain object.
Returns
SessionRecording