API Reference
Agent SDK API reference
Class: default
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.
Hierarchy
EventEmitter
↳
default
Constructors
constructor
• 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.
Parameters
Overrides
EventEmitter.constructor
Accessors
api
• get
api(): string
The url for the Cobrowse instance.
Returns
string
devices
• 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
license
• 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
Returns
void
recordings
• get
recordings(): SessionRecordingAPI
Namespace API for recordings. A recording in Cobrowse represents the video and event metadata for a recorded session.
Returns
SessionRecordingAPI
sessions
• get
sessions(): SessionsAPI
Namespace API for sessions. A session in Cobrowse represents a single screensharing activity with an agent.
Returns
SessionsAPI
token
• 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
Returns
void
users
• get
users(): UsersAPI
Namespace API for users.
Returns
UsersAPI
Methods
attachContext
▸ 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.
Parameters
Returns
Promise
<RemoteContext
>
The context returns contains methods specific to controlling the iframe
Interface: Device
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.
Events
fires
updated - The updated event will be fired when device data changes.
Hierarchy
EventEmitter
↳
Device
Properties
connectable
• connectable: boolean
Is the device in a state where it can accept a screenshare connection
custom_data
• custom_data: Record
<string
, any
>
The metadata you have associated with this device for discoverability and filtering by agents
device
• device: DeviceInfo
The device metadata exposed by the Cobrowse SDKs
id
• id: string
The unique ID of this device, generated internally by the Cobrowse SDKs. You cannot control this value.
last_active
• last_active: Date
The last time the device was seen
online
• online: boolean
Is the device currently connected to the Cobrowse service
Methods
on
▸ on(event
, listener
): Device
Listen for events on this device.
Parameters
Returns
Device
Overrides
EventEmitter.on
subscribe
▸ 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
▸ toJSON(): Device
Converts this device instance to a plain object.
Returns
Device
unsubscribe
▸ unsubscribe(): void
Unsubscribe from this device. Note: this is a browser only method and will not work from a NodeJS environment
Returns
void
Interface: DeviceInfo
Properties
app_id
• app_id: string
An identifier for the app being used (e.g. the domain name, or iOS app ID).
app_name
• app_name: string
The name of the app being used by the end user.
device
• device: string
The type of the device being used, e.g. iPhone or Chrome Browser.
device_locale
• device_locale: string
The preferred locale of the user's device.
device_timezone
• device_timezone: string
The timezone of the user's device.
full_device_control
• full_device_control: boolean
(Android only) Indicates whether full device remote control is currently available
os_version
• os_version: string
The OS version of the device.
platform
• platform: string
Which platform is being used, e.g. web, ios, android, windows, macos
sdk_version
• sdk_version: string
The version of the Cobrowse SDK that the device is running
Interface: DevicesAPI
Methods
get
▸ get(id
, query?
): Promise
<Device
>
Get a device by ID.
Parameters
Returns
Promise
<Device
>
list
▸ 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 date
seen_after
- only include devices that checked-in with the Cobrowse service after this date
Parameters
Returns
Promise
<Device
[]>
Interface: RemoteContext
Control Cobrowse hosted in an iframe from a parent context. Note: these are browser only methods and will not work from a NodeJS environment
Events
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)
Hierarchy
EventEmitter
↳
RemoteContext
Methods
androidBack
▸ androidBack(): Promise
<boolean
>
Triggers the Android Back button
Returns
Promise
<boolean
>
androidHome
▸ androidHome(): Promise
<boolean
>
Triggers the Android Home button
Returns
Promise
<boolean
>
clearAnnotations
▸ clearAnnotations(): Promise
<boolean
>
Clear all agent session annotations from the user's view.
Returns
Promise
<boolean
>
destroy
▸ destroy(): void
Destroy this remote context; stops listening for events and detaches from the iframe.
Returns
void
endSession
▸ endSession(): Promise
<boolean
>
End the current agent session.
Returns
Promise
<boolean
>
on
▸ on(event
, listener
): RemoteContext
Listen for events in this context.
Parameters
Returns
RemoteContext
Overrides
EventEmitter.on
setFullDevice
▸ 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
Returns
Promise
<boolean
>
setRemoteControl
▸ 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.
Parameters
Returns
Promise
<boolean
>
setTool
▸ setTool(tool
): Promise
<boolean
>
Set the tool to use in the Agent session.
Parameters
Returns
Promise
<boolean
>
Interface: Session
Represents a session in Cobrowse.
Events
fires
updated - fired when a session property changes
fires
ended - fired when a session transitions to the ended
state
Hierarchy
EventEmitter
↳
Session
Properties
activated
• activated: Date
The activation timestamp of the session. This is the time the user accepted the session.
agent
• agent: Object
Metadata about the agent that started the session
Type declaration
code
• code: string
A 6 digit, human friendly code that can be used to initiate a session
created
• created: Date
The date the session was first created (this will usually be before the activated
timestamp).
custom_data
• custom_data: Record
<string
, any
>
The metadata you have associated with this session for discoverability and filtering by agents.
device
• device: DeviceInfo
Metadata about the user's device
ended
• ended: Date
The timestamp the session was ended
full_device
• full_device: "off"
| "requested"
| "on"
| "rejected"
The state of the full device mode
id
• id: string
The unique ID for this screenshare session
recorded
• recorded: boolean
Was the session recorded
remote_control
• remote_control: "off"
| "requested"
| "on"
| "rejected"
The state of the remote control authorization for the session
state
• 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
• updated: Date
The timestamp of the last update to the session
Methods
end
▸ end(): Promise
<void
>
Ends this session.
Returns
Promise
<void
>
isActive
▸ 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
▸ 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
▸ isEnded(): boolean
True if the session is ended.
Returns
boolean
isPending
▸ 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
▸ on(event
, listener
): Session
Listen for events on this session.
Parameters
Returns
Session
Overrides
EventEmitter.on
▸ on(event
, listener
): Session
Parameters
Returns
Session
Overrides
EventEmitter.on
setFullDevice
▸ 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
Returns
Promise
<boolean
>
setRemoteControl
▸ 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
Returns
Promise
<void
>
subscribe
▸ 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
▸ toJSON(): Session
Converts this session instance to a plain object.
Returns
Session
unsubscribe
▸ unsubscribe(): void
Unsubscribe from this session. Note: this is a browser only method and will not work from a NodeJS environment
Returns
void
Interface: SessionRecording
Represents a session recording in Cobrowse.
Hierarchy
EventEmitter
↳
SessionRecording
Properties
id
• id: string
The unique ID for this recording
video
• video: Object
Provides access to the video for this recording
Type declaration
Methods
destroy
▸ destroy(): Promise
<any
>
Deletes this recording from the server
Returns
Promise
<any
>
events
▸ events(): Promise
<any
[]>
Gets the list of events for this recording
Returns
Promise
<any
[]>
toJSON
▸ toJSON(): SessionRecording
Converts this session instance to a plain object.
Returns
SessionRecording
Interface: SessionRecordingAPI
Methods
destroy
▸ destroy(): Promise
<SessionRecording
>
Deletes a recording by its ID
Returns
Promise
<SessionRecording
>
get
▸ get(id
, query?
): Promise
<SessionRecording
>
Get a recording by (Session) ID
Parameters
Returns
Promise
<SessionRecording
>
Interface: SessionsAPI
Methods
create
▸ create(resource?
, query?
): Promise
<Session
>
Create a session, optionally passing additional query parameters.
Parameters
Returns
Promise
<Session
>
get
▸ get(id
, query?
): Promise
<Session
>
Get a session by ID
Parameters
Returns
Promise
<Session
>
list
▸ list(query?
): Promise
<Session
[]>
List sessions, 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' }
activated_before
- only include sessions that were activated before this date. Useful for paging.
activated_after
- only include devices that were activated after this date. Useful for paging.
agent
- Administrator may set this to all
to list sessions for all agents. Agent roles may only list their own sessions.
state
- Filter by session that are in one of the supported states: pending
, authorizing
, active
, ended
.
Parameters
Returns
Promise
<Session
[]>
Interface: User
Represents a user in Cobrowse.
Hierarchy
EventEmitter
↳
User
Properties
id
• id: string
Methods
on
▸ on(event
, listener
): User
Listen for events on this user.
Parameters
Returns
User
Overrides
EventEmitter.on
toJSON
▸ toJSON(): User
Converts this device instance to a plain object.
Returns
User
Interface: UsersAPI
Methods
get
▸ get(id
, query?
): Promise
<User
>
Get a user by ID and optionally filter by query parameters.
Parameters
Returns
Promise
<User
>
Last updated