Jump to: navigation, search

Co-browse API

This API provides methods and callbacks to work with Co-browse and can be used to implement a custom UI for co-browsing.

See Integrated JavaScript Application#Obtaining Chat and Co-browse APIs for information on accessing this API.

Co-browse in iframes

Some Co-browse UI elements such as the the co-browsing button and toolbar should not appear when Co-browse is in an iframe. Common Co-browse UI elements such as notifications that an element is masked should appear whether or no Co-browse is in an iframe. As such, there are two contexts for the Co-browse JavaScript API:

  • Top context, available when Co-browse is not rendered in an iframe.
  • Child context, used when a page is rendered in an iframe. For the child context, a subset of the top context API is available.


The isTopContext variable can be used determine which context Co-browse is rendered in. isTopContext is passed to the onReady method and equals true if Co-browse is rendered in the top context and false otherwise.


var _genesys = {
    cobrowse: {
        onReady: function(api, isTopContext) {
            // common functionality
            api.onMaskedElement.add(function() {/* deal with masked elements here*/});
            if (!isTopContext) {
            // top context functionality goes below

Signals and Callbacks

The Co-browse API exposes a number of signals in both the top and child contexts. Each signal is object with the three following methods:

  • add(function)—adds a callback
  • addOnce(function)—adds a callback that will be executed only once
  • remove(function)—removes a callback

The naming convention for signal names begins with "on" and follows the format onSomethingHappened.

Signals act similar to deferred objects. If you add a callback to an event that has already happened, the callback will be called immediately. For example, if you add a callback to the onAgentJoined signal when the event has already happened, the callback will be called immediately.

Session Object

Many callbacks receive a session object as an argument. This object has the following properties:

  • token—String containing the session token shared with the agent and possibly shown in the UI. The token is a 9 digit string such as "535176834".
  • agents—Array of connected agents. Each element in the array is an object with no properties.

Common API

The following elements and properties are available from both the top and child Co-browse contexts:


Service elements do not show up in the agent's view. This function is used to mark service elements in a custom Co-browse UI.


  • element—HTML element that will be masked.
Elements must be marked as service elements before they are added to the DOM
The markServiceElement() method should not be used to hide sensitive information. Business functions like DOM Control or Data Masking should be used for sensitive content such as private user data.

Plain DOM Example:

function createCustomCobrowseUI(cobrowseApi) {
    var toolbar = document.createElement('div');
    toolbar.className = 'cobrowseToolbar';
    toolbar.textContent = 'Co-browse is going on';
    cobrowseApi.markServiceElement(toolbar); // don't show the toolbar to agents
    cobrowseApi.onConnected.add(function() {

jQuery Example:

// Create a simple jQuery plugin
$.fn.cbMarkNode = function() {
    return this.each(function() {
// And then:
$('<div class="cobrowseToolbar">Co-browse is going on</div>').cbMarkNode().appendTo('body');


This signal is dispatched when Co-browse encounters an element that is subject to data masking.


  • element—HTML Element

This signal is dispatched multiple times when Co-browse initiates and can be dispatched again if a masked element is added to the page dynamically.


cobrowseApi.onMaskedElement.add(function(element) {
        content: 'Content of this elements is masked for representatives.'

Top Context API

The following methods and properties are available only when Co-browse is rendered in the top context.


This method returns a boolean with the value of true when the browser is supported and false otherwise. The built-in integration module uses this function to show a message if a user tries to start Co-browse in an unsupported browser. You may use it, for example, to hide the Co-browse button completely.


This method instantiates a new Co-browse session. It will throw an error if the browser is not supported.


This method exits and ends an ongoing Co-browse session.


This signal is dispatched after the page is loaded and the Co-browse business logic is initialized.


  • sessionSession object representing the ongoing session or null if there is no ongoing session.


cobrowseApi.onInitialized.add(function(session) {
    if (!session) {
    } else {


This signal is dispatched when a Co-browse session is successfully started and joined by the master such as when the Co-browse button is pressed or when startSession() is called.



function notifyCobrowseStarted(session) {
    alert('Co-browse has started. Spell this session token to our representative: ' + session.token);


This signal is dispatched when an agent successfully joins a session.


  • agent—Object representing the new agent. This object has no properties.
  • sessionSession object representing the ongoing session.


cobrowseApi.onAgentJoined.add(function(agent, session) {
    alert('Representative has joined the session');


This signal is dispatched when the slave user initiates navigation such as refresh, back, forward, or when the agent enters a URL into the slave Co-browse UI. Signal is dispatched a few seconds before the navigation happens. This can be used to, for example, send a warning to the user or disable the Exit session button before navigation.


  • details—Object containing the following navigation detail fields:
    • command—String with the value of back, refresh, forward, or url.
    • url—Optional string that is present only if the command field has the value of url


// Let's assume we have a "growl" function available to show growl-like notifications
cobrowseApi.onAgentNavigated.add(function(details) {
    if (details.url) {
        growl('Representative navigated to the page: ' + details.url);
    } else {
        growl('Representative has pressed the "' + details.command + '" button. Page will be refreshed');


This signal is dispatched when the navigation request from the agent fails to execute such as when the agent navigates forward when there is no forward history. You can use this signal to to re-enable the Exit button and/or show a notification.

The callback receives no arguments.


// Let's assume we have a "growl" function available to show growl-like notifications
cobrowseApi.onNavigationFailed.add(function() {
    growl('Navigation request by representative has failed');


This signal is dispatched when a Co-browse session ends.


  • details—Object with the follwing field:
    • reason—Field with value of a string or undefined. Possible string values:
      • self—The user has exited the session by clicking the Exit button or calling the exitSession() API method.
      • external—The agent has closed the session. Some server errors may also result in this value.
      • timeout—The session has timed out such as when a user reopens a page with an expired Co-browse cookie.
      • intactivityTimeout—The agent did not join a session in the configured amount of time.
      • error—There is an error such as a critical misconfiguration.


var cbEndedMessages = {
    self: 'You exited Co-browse session. Co-browse terminated',
    external: 'Co-browse session ended',
    timeout: 'Co-browse session timed out',
    inactivityTimeout: 'Agent did not join. Closing Co-browse session.',
cobrowseApi.onSessionEnded.add(function(details) {
    alert(cbEndedMessages[details.reason] || 'Something went wrong. Co-browse terminated.');
This page was last modified on December 2, 2014, at 12:57.


Comment on this article:

blog comments powered by Disqus