# 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 <a href="#constructor" id="constructor"></a>

• **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.

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

**Parameters**

| Name       | Type                      | Description                                                                                             |
| ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------- |
| `token?`   | `string`                  | The [JWT](https://docs.cobrowse.io/agent-side-integrations/json-web-tokens-jwts) for API authorization. |
| `options?` | `Record`<`string`, `any`> | Options for configuring this instance of CobrowseAPI.                                                   |

**Overrides**

EventEmitter.constructor

### Accessors

#### api <a href="#api" id="api"></a>

• `get` **api**(): `string`

The url for the Cobrowse instance.

**Returns**

`string`

***

#### devices <a href="#devices" id="devices"></a>

• `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 <a href="#license" id="license"></a>

• `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`

***

#### recordings <a href="#recordings" id="recordings"></a>

• `get` **recordings**(): `SessionRecordingAPI`

Namespace API for recordings. A recording in Cobrowse represents the video and event metadata for a recorded session.

**Returns**

`SessionRecordingAPI`

***

#### sessions <a href="#sessions" id="sessions"></a>

• `get` **sessions**(): `SessionsAPI`

Namespace API for sessions. A session in Cobrowse represents a single screensharing activity with an agent.

**Returns**

`SessionsAPI`

***

#### token <a href="#token" id="token"></a>

• `get` **token**(): `string`

The [JWT](https://docs.cobrowse.io/agent-side-integrations/json-web-tokens-jwts) 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](https://docs.cobrowse.io/agent-side-integrations/json-web-tokens-jwts) 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`

***

#### users <a href="#users" id="users"></a>

• `get` **users**(): `UsersAPI`

Namespace API for users.

**Returns**

`UsersAPI`

### Methods

#### attachContext <a href="#attachcontext" id="attachcontext"></a>

▸ **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.

```javascript
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

## 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](https://docs.cobrowse.io/sdk-features/identify-your-devices) to add metadata for filtering.

```javascript
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 <a href="#connectable" id="connectable"></a>

• **connectable**: `boolean`

Is the device in a state where it can accept a screenshare connection

***

#### custom\_data <a href="#custom_data" id="custom_data"></a>

• **custom\_data**: `Record`<`string`, `any`>

The metadata you have associated with this device for discoverability and filtering by agents

***

#### device <a href="#device" id="device"></a>

• **device**: `DeviceInfo`

The device metadata exposed by the Cobrowse SDKs

***

#### id <a href="#id" id="id"></a>

• **id**: `string`

The unique ID of this device, generated internally by the Cobrowse SDKs. You cannot control this value.

***

#### last\_active <a href="#last_active" id="last_active"></a>

• **last\_active**: `Date`

The last time the device was seen

***

#### online <a href="#online" id="online"></a>

• **online**: `boolean`

Is the device currently connected to the Cobrowse service

### Methods

#### on <a href="#on" id="on"></a>

▸ **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 <a href="#subscribe" id="subscribe"></a>

▸ **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 <a href="#tojson" id="tojson"></a>

▸ **toJSON**(): `Device`

Converts this device instance to a plain object.

**Returns**

`Device`

***

#### unsubscribe <a href="#unsubscribe" id="unsubscribe"></a>

▸ **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 <a href="#app_id" id="app_id"></a>

• **app\_id**: `string`

An identifier for the app being used (e.g. the domain name, or iOS app ID).

***

#### app\_name <a href="#app_name" id="app_name"></a>

• **app\_name**: `string`

The name of the app being used by the end user.

***

#### device <a href="#device" id="device"></a>

• **device**: `string`

The type of the device being used, e.g. iPhone or Chrome Browser.

***

#### device\_locale <a href="#device_locale" id="device_locale"></a>

• **device\_locale**: `string`

The preferred locale of the user's device.

***

#### device\_timezone <a href="#device_timezone" id="device_timezone"></a>

• **device\_timezone**: `string`

The timezone of the user's device.

***

#### full\_device\_control <a href="#full_device_control" id="full_device_control"></a>

• **full\_device\_control**: `boolean`

(Android only) Indicates whether full device remote control is currently available

***

#### os\_version <a href="#os_version" id="os_version"></a>

• **os\_version**: `string`

The OS version of the device.

***

#### platform <a href="#platform" id="platform"></a>

• **platform**: `string`

Which platform is being used, e.g. web, ios, android, windows, macos

***

#### sdk\_version <a href="#sdk_version" id="sdk_version"></a>

• **sdk\_version**: `string`

The version of the Cobrowse SDK that the device is running

## Interface: DevicesAPI

### Methods

#### get <a href="#get" id="get"></a>

▸ **get**(`id`, `query?`): `Promise`<`Device`>

Get a device by ID.

```javascript
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 <a href="#list" id="list"></a>

▸ **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

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

**Parameters**

| Name     | Type                         |
| -------- | ---------------------------- |
| `query?` | `Record`<`string`, `string`> |

**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 <a href="#androidback" id="androidback"></a>

▸ **androidBack**(): `Promise`<`boolean`>

Triggers the Android Back button

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

**Returns**

`Promise`<`boolean`>

***

#### androidHome <a href="#androidhome" id="androidhome"></a>

▸ **androidHome**(): `Promise`<`boolean`>

Triggers the Android Home button

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

**Returns**

`Promise`<`boolean`>

***

#### clearAnnotations <a href="#clearannotations" id="clearannotations"></a>

▸ **clearAnnotations**(): `Promise`<`boolean`>

Clear all agent session annotations from the user's view.

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

**Returns**

`Promise`<`boolean`>

***

#### destroy <a href="#destroy" id="destroy"></a>

▸ **destroy**(): `void`

Destroy this remote context; stops listening for events and detaches from the iframe.

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

**Returns**

`void`

***

#### endSession <a href="#endsession" id="endsession"></a>

▸ **endSession**(): `Promise`<`boolean`>

End the current agent session.

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

**Returns**

`Promise`<`boolean`>

***

#### on <a href="#on" id="on"></a>

▸ **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 <a href="#setfulldevice" id="setfulldevice"></a>

▸ **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.

```javascript
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 <a href="#setremotecontrol" id="setremotecontrol"></a>

▸ **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.

```javascript
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 <a href="#settool" id="settool"></a>

▸ **setTool**(`tool`): `Promise`<`boolean`>

Set the tool to use in the Agent session.

```javascript
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`>

## 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 <a href="#activated" id="activated"></a>

• **activated**: `Date`

The activation timestamp of the session. This is the time the user accepted the session.

***

#### agent <a href="#agent" id="agent"></a>

• **agent**: `Object`

Metadata about the agent that started the session

**Type declaration**

| Name     | Type     |
| -------- | -------- |
| `colour` | `string` |
| `id`     | `string` |
| `name`   | `string` |

***

#### code <a href="#code" id="code"></a>

• **code**: `string`

A 6 digit, human friendly code that can be used to initiate a session

***

#### created <a href="#created" id="created"></a>

• **created**: `Date`

The date the session was first created (this will usually be before the `activated` timestamp).

***

#### custom\_data <a href="#custom_data" id="custom_data"></a>

• **custom\_data**: `Record`<`string`, `any`>

The metadata you have associated with this session for discoverability and filtering by agents.

***

#### device <a href="#device" id="device"></a>

• **device**: `DeviceInfo`

Metadata about the user's device

***

#### ended <a href="#ended" id="ended"></a>

• **ended**: `Date`

The timestamp the session was ended

***

#### full\_device <a href="#full_device" id="full_device"></a>

• **full\_device**: `"off"` | `"requested"` | `"on"` | `"rejected"`

The state of the full device mode

***

#### id <a href="#id" id="id"></a>

• **id**: `string`

The unique ID for this screenshare session

***

#### recorded <a href="#recorded" id="recorded"></a>

• **recorded**: `boolean`

Was the session recorded

***

#### remote\_control <a href="#remote_control" id="remote_control"></a>

• **remote\_control**: `"off"` | `"requested"` | `"on"` | `"rejected"`

The state of the remote control authorization for the session

***

#### state <a href="#state" id="state"></a>

• **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 <a href="#updated" id="updated"></a>

• **updated**: `Date`

The timestamp of the last update to the session

### Methods

#### end <a href="#end" id="end"></a>

▸ **end**(): `Promise`<`void`>

Ends this session.

**Returns**

`Promise`<`void`>

***

#### isActive <a href="#isactive" id="isactive"></a>

▸ **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 <a href="#isauthorizing" id="isauthorizing"></a>

▸ **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 <a href="#isended" id="isended"></a>

▸ **isEnded**(): `boolean`

True if the session is ended.

**Returns**

`boolean`

***

#### isPending <a href="#ispending" id="ispending"></a>

▸ **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 <a href="#on" id="on"></a>

▸ **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 <a href="#setfulldevice" id="setfulldevice"></a>

▸ **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 <a href="#setremotecontrol" id="setremotecontrol"></a>

▸ **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 <a href="#subscribe" id="subscribe"></a>

▸ **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 <a href="#tojson" id="tojson"></a>

▸ **toJSON**(): `Session`

Converts this session instance to a plain object.

**Returns**

`Session`

***

#### unsubscribe <a href="#unsubscribe" id="unsubscribe"></a>

▸ **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 <a href="#id" id="id"></a>

• **id**: `string`

The unique ID for this recording

***

#### video <a href="#video" id="video"></a>

• **video**: `Object`

Provides access to the video for this recording

**Type declaration**

| Name    | Type                      |
| ------- | ------------------------- |
| `fetch` | () => `Promise`<`any`>    |
| `url`   | () => `Promise`<`string`> |

### Methods

#### destroy <a href="#destroy" id="destroy"></a>

▸ **destroy**(): `Promise`<`any`>

Deletes this recording from the server

**Returns**

`Promise`<`any`>

***

#### events <a href="#events" id="events"></a>

▸ **events**(): `Promise`<`any`\[]>

Gets the list of events for this recording

**Returns**

`Promise`<`any`\[]>

***

#### toJSON <a href="#tojson" id="tojson"></a>

▸ **toJSON**(): `SessionRecording`

Converts this session instance to a plain object.

**Returns**

`SessionRecording`

## Interface: SessionRecordingAPI

### Methods

#### destroy <a href="#destroy" id="destroy"></a>

▸ **destroy**(): `Promise`<`SessionRecording`>

Deletes a recording by its ID

**Returns**

`Promise`<`SessionRecording`>

***

#### get <a href="#get" id="get"></a>

▸ **get**(`id`, `query?`): `Promise`<`SessionRecording`>

Get a recording by (Session) ID

**Parameters**

| Name     | Type                         |
| -------- | ---------------------------- |
| `id`     | `string`                     |
| `query?` | `Record`<`string`, `string`> |

**Returns**

`Promise`<`SessionRecording`>

## Interface: SessionsAPI

### Methods

#### create <a href="#create" id="create"></a>

▸ **create**(`resource?`, `query?`): `Promise`<`Session`>

Create a session, optionally passing additional query parameters.

**Parameters**

| Name        | Type                         |
| ----------- | ---------------------------- |
| `resource?` | `any`                        |
| `query?`    | `Record`<`string`, `string`> |

**Returns**

`Promise`<`Session`>

***

#### get <a href="#get" id="get"></a>

▸ **get**(`id`, `query?`): `Promise`<`Session`>

Get a session by ID

**Parameters**

| Name     | Type                         |
| -------- | ---------------------------- |
| `id`     | `string`                     |
| `query?` | `Record`<`string`, `string`> |

**Returns**

`Promise`<`Session`>

***

#### list <a href="#list" id="list"></a>

▸ **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**

| Name     | Type                         |
| -------- | ---------------------------- |
| `query?` | `Record`<`string`, `string`> |

**Returns**

`Promise`<`Session`\[]>

## Interface: User

Represents a user in Cobrowse.

### Hierarchy

* `EventEmitter`

  ↳ **`User`**

### Properties

#### id <a href="#id" id="id"></a>

• **id**: `string`

### Methods

#### on <a href="#on" id="on"></a>

▸ **on**(`event`, `listener`): `User`

Listen for events on this user.

**Parameters**

| Name       | Type                       |
| ---------- | -------------------------- |
| `event`    | `"updated"`                |
| `listener` | (`user`: `User`) => `void` |

**Returns**

`User`

**Overrides**

EventEmitter.on

***

#### toJSON <a href="#tojson" id="tojson"></a>

▸ **toJSON**(): `User`

Converts this device instance to a plain object.

**Returns**

`User`

## Interface: UsersAPI

### Methods

#### get <a href="#get" id="get"></a>

▸ **get**(`id`, `query?`): `Promise`<`User`>

Get a user by ID and optionally filter by query parameters.

**Parameters**

| Name     | Type                         |
| -------- | ---------------------------- |
| `id`     | `string`                     |
| `query?` | `Record`<`string`, `string`> |

**Returns**

`Promise`<`User`>