Cobrowse.io Docs
  • Getting started
  • SDK Installation
    • Web
    • iOS
    • Android
    • React Native
    • Flutter
    • .NET Mobile
    • macOS
    • Windows
  • SDK Features
    • Account config
    • Identify your devices
    • Use 6-digit codes
    • Redact sensitive data
    • Viewing PDFs
    • Universal Cobrowse
    • Customize the interface
      • Active session controls
      • 6-digit code screen
      • User consent dialog
      • Remote control consent dialog
      • Full device consent dialog
      • Localization / translation
    • Initiate sessions with push
    • Listening for events
    • Full device capabilities
      • Full device screen sharing
      • Full device remote control
      • Managing full device mode
    • Advanced configuration
      • Starting and stopping the SDK
      • Declaring capabilities
      • Intercepting mobile SDK network requests
      • Web
        • IFrames support
        • IE 11 polyfills
        • Cross-domain session support
        • Ignore Views
      • iOS
        • Alternate render method
        • Custom touch handling
      • Android
        • Backporting TLS to older Android versions
  • Agent-side integrations
    • Agent-side overview
    • Platform integrations
      • Zendesk
      • Salesforce
        • Migrating from legacy to v2
        • Salesforce (Legacy)
      • Genesys
        • Genesys Cloud
        • Engage Workspace Web Edition (WWE)
        • Engage Workspace Desktop Edition (WDE)
      • Intercom
      • Freshworks
      • Talkdesk
      • NICE
    • Custom integrations
    • Agent SDK
      • API Reference
      • Sample code snippets
    • Authentication (JWTs)
      • JWT Policies
    • Authentication (SAML 2.0)
    • IFrame embeds
  • Enterprise self-hosting
    • Self-hosting overview
    • Docker Compose
    • Helm chart
      • Image Pull Secret
      • Environment Variables
      • Optional recording components
      • Pod Annotations
    • AWS terraform
      • AWS metrics configuration
    • Azure terraform
      • Azure metrics configuration
    • GCP terraform
      • GCP metrics configuration
    • Sizing guidelines
    • Running your instance
      • Adding a superuser
      • Limiting account creation
      • Limiting magic link recipients
      • Configuring SMTP
      • Managing your deployment
    • Monitoring your instance
      • Available metrics
      • Self-Hosted Prometheus
    • Advanced configuration
      • Air gap configuration
      • Pin web SDK version
      • L7 firewall configuration
      • Docker proxy configuration
    • Troubleshooting
Powered by GitBook
On this page
  • List only relevant sessions or devices using filters
  • Listen for updates on a session or device
  • Control an IFrame embedded in my support agents' portal
  • Access and update the session in the IFrame
  • Add extra data to a session from the agent side
  • Completely replace the session UI with my own design
  • Check the number of active sessions
  • End the session after a chat/interaction, or after the browser is closed
  • Leave without ending the session

Was this helpful?

  1. Agent-side integrations
  2. Agent SDK

Sample code snippets

Build the experience that you want for your support agents with our powerful agent SDK. Here are some examples of commonly required functionality.

PreviousAPI ReferenceNextAuthentication (JWTs)

Last updated 1 year ago

Was this helpful?

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

const sessions = await cobrowse.sessions.list({
    filter_user_id: 'xxxx'
    // other filtering properties are also supported.
    // See the API reference for more.
    state: ['ended']
})

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

const sessions = await cobrowse.sessions.list({
    // add your filters in here, e.g.
    filter_user_id: 'xxxx', // customData filters start with "filter_"
    state: ['ended'] // session property filters 
})

// subscribe to updates for these Sessions
sessions.forEach((session) => {
    session.subscribe()
    session.on('updated', () => console.log('session was updated', session.id)
})

Subscribing to Device resources

const devices = await cobrowse.devices.list({
    // add your filters in here, e.g.
    filter_user_id: 'xxxx', // customData filters start with "filter_"
})

// subscribe to updates for these Devices
devices.forEach((device) => {
    device.subscribe()
    device.on('updated', () => console.log('device was updated', device.id))
})

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

const cobrowse = new CobrowseAPI() // JWT not required
    
// attach to iframe (make sure it has loaded!)
const frameEl = document.getElementById('myIframe')
const ctx = await cobrowse.attachContext(frameEl)
    
// listen for updates to session
ctx.on('session.updated', (session) => {
    console.log('session was updated', session)
    if (session.ended) {
        console.log('session has ended')
        ctx.destroy()
    }
})
    
// interact with the iframe
await ctx.setTool('laser')
await ctx.clearAnnotations()
await ctx.setFullDevice('requested')
await ctx.setRemoteControl('requested')
await ctx.endSession()

Access and update the session in the IFrame

Sometimes it's useful to access the session that was created in an IFrame in order to modify some properties that cannot be directly controlled through the IFrame methods. First you'll need to get the access to the session from the IFrame:

const cobrowse = new CobrowseAPI(...) 
    
// attach to iframe (make sure it has loaded!)
const frameEl = document.getElementById('myIframe')
const ctx = await cobrowse.attachContext(frameEl)

// track the latest session that has been loaded into (or created by)
// the iframe 
let currentSession = null
ctx.on('session.updated', session => {
    latestSession = session
})

Then at some point later, when you want to make a change to the session, you use the session object that was passed in the session.updated event. Note: you will need to configure a JWT in the agent SDK to call some methods that require authentication on the session object.

Add extra data to a session from the agent side

Sometimes the data that you want to associate with a session may not be available from the user-side to use with the device side SDKs. In this case it is possible to add custom data from the agent side that will remain associated with a session.

// create an API instance
// Note: a valid JWT is required to modify the session
const cobrowse = new CobrowseAPI(token)

// This function can be used to watch a window (from window.open()), or
// an Iframe, for changes in the Cobrowse session. When a new session is
// detected we can then update the custom_data field to include extra
// data not provided by the device directly. 
async function watch (windowOrIframe) {
  const ctx = await cobrowse.attachContext(windowOrIframe)
  console.log('Watching', windowOrIframe, 'for cobrowse session changes')
  ctx.on('session.loaded', async (session) => {
    console.log('Detected a change in Cobrowse session', session)
    // Modify the session however is required, in this example
    // we'll add two new custom_data properties
    const myData = { some_id: '12345', another_id: '54321' }
    // Save the changes back to the session
    await session.update({ custom_data: myData })
    console.log('Updated session custom data with', myData)
  })
}

function openSessionById (sessionId) {
  // In this example we'll open a new window for the Cobrowse session,
  // using the window.open() browser API available in JavaScript.
  // This would work equalliy well when connecting to a device via
  // our /connect or /code embed APIs. Additionally, this would work 
  // when using an Iframe rather than window.open().
  watch(window.open(`${cobrowse.api}/session/${sessionId}?end_action=none&token=${cobrowse.token}`))
}

// Call this function with a valid session ID. You can obtain session IDs
// either via the REST API, the Cobrowse attachContext() APIs,or your own
// out-of-band channel (e.g. your CRM integration or livechat platform)
openSessionById('some session id here')

See the links below for more on how to generate a token or choose the best link to embed.

Completely replace the session UI with my own design

Check the number of active sessions

It's often useful to know how many active sessions are in progress. The sample below provides a basic way to list all active sessions for your account.

// token must have role: administrator claim
const cobrowse = new CobrowseAPI(token)
const sessions = await cobrowse.sessions.list({
    state: ['active'],
    agent: 'all',
    limit: 1000
})
console.log('Active sessions', sessions.length)

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. Using the device-side SDKs to call session.end() (the exact syntax will depend on the SDK used)

  2. Using the default agent-side UI by clicking the red "hang-up" icon

  3. 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.

See the API reference for full details on what you can do . You may also find the embed documentation useful:

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 , or try the demo .

Using the agent SDK APIs to programatically end the session, either via the , or via an with a JWT.

custom data
API Reference
using an IFrame context
IFrame embeds
IFrame embeds
Authentication (JWTs)
source code on GitHub
here
IFrame context
API call