How do I...
Our agent SDK is a powerful toolkit to build the experience that you want for your support agents. Here we have put together a number of examples of commonly required functionality.

List only relevant sessions or devices using filters

Using our custom data mechanism you can add metadata that lets you link Cobrowse device and session records with your users. You can use this same data to filter when listing resources via our agent SDK.
You can construct a filter query for a custom data entry by prepending "filter_" to the key of your custom data. For example, user_id becomes filter_user_id:
1
const sessions = await cobrowse.sessions.list({
2
filter_user_id: 'xxxx'
3
// other filtering properties are also supported.
4
// See the API reference for more.
5
state: ['ended']
6
})
Copied!
The same system applied to both Session resources and Device resources. See the API reference for the available parameters:

Listen for updates on a session or device

Often it's useful to know when the state of a session or device resource changes so you can provide a user interface that updates in real time. This is possible through our agent SDK.

Subscribing to Session resources

1
const sessions = await cobrowse.sessions.list({
2
// add your filters in here, e.g.
3
filter_user_id: 'xxxx', // customData filters start with "filter_"
4
state: ['ended'] // session property filters
5
})
6
7
// subscribe to updates for these Sessions
8
sessions.forEach((session) => {
9
session.subscribe()
10
session.on('updated', () => console.log('session was updated', session.id)
11
})
Copied!

Subscribing to Device resources

1
const devices = await cobrowse.devices.list({
2
// add your filters in here, e.g.
3
filter_user_id: 'xxxx', // customData filters start with "filter_"
4
})
5
6
// subscribe to updates for these Devices
7
devices.forEach((device) => {
8
device.subscribe()
9
device.on('updated', () => console.log('device was updated', device.id)
10
})
Copied!

Control an IFrame embedded in my support agents' portal

When integrating Cobrowse to your own custom helpdesk or CRM, many customers need to control some aspects within the Cobrowse IFrames, such as switch the agent tool, or ending the session. We provide an easy mechanism for this (no JWT required!)
1
const cobrowse = new CobrowseAPI() // JWT not required
2
3
// attach to iframe (make sure it has loaded!)
4
const frameEl = document.getElementById('myIframe')
5
const ctx = await cobrowse.attachContext(frameEl)
6
7
// listen for updates to session
8
ctx.on('session.updated', (session) => {
9
console.log('session was updated', session)
10
if (session.ended) {
11
console.log('session has ended')
12
ctx.destroy()
13
}
14
})
15
16
// interact with the iframe
17
await ctx.setTool('laser')
18
await ctx.clearAnnotations()
19
await ctx.setFullDevice(true)
20
await ctx.setRemoteControl('requested')
21
await ctx.endSession()
Copied!
See the API reference for full details on what you can do using an IFrame context. You may also find the embed documentation useful:

Completely replace the session UI with my own design

Cobrowse is designed to be fully customizable, including the agent side experience. We've put together a small example to show how to build your own in-session UI. Find the full source code on GitHub, or try the demo here.

Check the number of active sessions

For customers using our concurrency based licenses, it's often useful to know how many active sessions are in progress, and therefore how close to your license limits you are. The sample below provides a basic way to list all active sessions for your account.
1
// token must have role: administrator claim
2
const cobrowse = new CobrowseAPI(token)
3
const sessions = await cobrowse.sessions.list({
4
state: ['active'],
5
agent: 'all',
6
limit: 1000
7
})
8
console.log('Active sessions', sessions.length)
Copied!
Note: if you have more than 1000 concurrently active sessions you will need to add paging to this example to count them all.

End the session after a chat/interaction, or after the browser is closed

There's multiple ways to end a Cobrowse session, which one to use will depend on your use case. The options include:
  1. 1.
    Using the device-side SDKs to call session.end() (the exact syntax will depend on the SDK used)
  2. 2.
    Using the default agent-side UI by clicking the red "hang-up" icon
  3. 3.
    Using the agent SDK APIs to programatically end the session, either via the IFrame context, or via an API call with a JWT.
  4. 4.
    Letting the server end the session after a timeout. If the device or agent closes the app or browser the server will clean up sessions automatically after approximately 5 minutes of inactivity.

Leave without ending the session

Sometimes it's useful to be able to leave the session without ending it, for example when a supervisor is monitoring a number of ongoing sessions needs to switch between them. You can simply close the tab or remove the IFrame without ending the session to achieve this.