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.

const token = await myJWTGeneratingFunction()
const cobrowse = new CobrowseAPI(token, { api: 'https://cobrowse.example.com' })

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.

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

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.

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))

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.

const cobrowse = new CobrowseAPI(...)
const device = await cobrowse.devices.get('some device id here')

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

const cobrowse = new CobrowseAPI(...)
const devices = await cobrowse.devices.list({ filter_user_id: 'abcdef' } })

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

const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.androidBack()

Returns

Promise<boolean>


androidHome

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

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

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

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

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.

const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.setFullDevice('requested')

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.

const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.setRemoteControl('requested')

Parameters

Returns

Promise<boolean>


setTool

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

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 →) activeended. 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