Start Sessions with Click-To-Chat or Collaborative Browser Sharing

Using JavaScript

To start a collaborative browser sharing session or a click-to-chat session, you must first reference an external JavaScript file that is included on your Bomgar Appliance. You must then tell the API the hostname from which the JavaScript files and other resources should be lazily loaded. This hostname should not include the protocol (e.g., support.example.com). Both of these elements should be included in the head of your web page, as shown in the example below.

<head>

<script type="text/javascript" src="https://support.example.com/api/start_session.js"></script>

<script type="text/javascript">BG.setSite("support.example.com");</script>

</head>

Then, within the body, you must include an event attribute to trigger a session start. In most cases, this will be an onclick event attribute on an anchor or button element. With this event, call the BG.start method, using the arguments to start the session with session key submission, representative selection, or issue submission.

BG.start(startType, options)

The startType can be either BG.START_TYPE.CHAT or BG.START_TYPE.BROWSER. This determines which type of session will be launched. The options parameter expects a generic JavaScript object which contains set properties (see options Properties).

IMPORTANT! Your HTML page must have a valid standards-compliant Doctype. View recommended Doctype declarations at http://www.w3.org/QA/2002/04/valid-dtd-list.html.

Below are several examples of the script.

Examples

Several common examples are listed below, though more are possible.

Starting a Browser Session with a Session Key

BG.start(BG.START_TYPE.BROWSER, {

sessionKey: '1728331'

});

Starting a Browser Session with Representative Information

BG.start(BG.START_TYPE.BROWSER, {

rep: {

id: 30,

name: 'Admin'

}

});

Starting a Browser Session with a Session Key and Custom Fields

BG.start(BG.START_TYPE.BROWSER, {

sessionKey: '8679485',

attributes: {

external_key: 'abc123',

custom_field1: 'Custom Value',

custom_field2: 123

}

});

Starting a Browser Session with a Session Key and a Specified Language

BG.start(BG.START_TYPE.BROWSER, {

sessionKey: '8679485',

locale: 'en-us'

});

Starting a Browser Session with an Issue Object (by ID) and Customer Information

BG.start(BG.START_TYPE.BROWSER, {

issue: {

id: 12

},

customer:

{

name: 'Customer Name',

company: 'Company Name',

company_code: 'Company Code',

details: 'Issue Details'

}

});

Starting a Browser Session with an Issue Object (by Code Name) and Skills

BG.start(BG.START_TYPE.BROWSER, {

issue: {

codeName: 'Other'

}

skills: ["skill1", "skill2"]

});

Starting a Browser Session with an Issue Form Element

BG.start(BG.START_TYPE.BROWSER, {

issue: document.getElementById('formID')

});

Example Issue Form

<form id="id">

<input type="hidden" name="codeName" value="Other" />

<input type="hidden" name="skills" value="skill1,skill2" />

<input type="hidden" name="customer.name" value="Customer Name" />

<input type="hidden" name="customer.company" value="Company Name" />

<input type="hidden" name="customer.company_code" value="Company Code" />

<input type="hidden" name="customer.details" value="Issue Details" />

<input type="hidden" name="session.custom.external_key" value="abc123" />

<input type="hidden" name="session.custom.custom_field1" value="Custom Value" />

<input type="hidden" name="session.custom.custom_field2" value="123" />

</form>

Any of the sessions above can be called as click-to-chat sessions by changing the start type to BG.START_TYPE.CHAT.

Starting a Click-to-Chat Session with a Session Key

BG.start(BG.START_TYPE.CHAT, {

sessionKey: '8347482'

});

Click-to-chat sessions may have an additional uiOptions object.

Starting a Click-to-Chat Session with a Session Key and fallbackToFullWindow

BG.start(BG.START_TYPE.CHAT, {

sessionKey: '7683902',

uiOptions: {

fallbackToFullWindow: false

}

});

options Properties

The options parameter accepts the following possible arguments:

Name Type Required or Exclusive? Description
sessionKey String Exclusive – Start Method The numeric session key.
rep Object Exclusive – Start Method An object identifying the representative with whom to start the session. See the table below.
issue DOM Element Exclusive – Start Method

A DOM element specifying the support issue. The DOM element can be retrieved using document.getElementById('id'). See the table below.

issue Object Exclusive – Start Method

An object specifying the support issue. See the table below.

skills Array No The skills to apply to this session for the purpose of routing. Can be combined with any start method.
customer Object No An object providing information about the customer. Can be combined with any start method. See the table below.
locale

String

No

The locale code of the language to be used for this customer client. The language must be installed on your Bomgar Appliance. To see which languages are installed, go to /login > Localization > Languages.

Available language packages may include English (en-us), German (de), Latin American Spanish (es), EU Spanish (es-sp), EU French (fr), Italian (it), Dutch (nl), Brazilian Portuguese (pt-br), EU Portuguese (pt-pt), Swedish (sv-se), Turkish (tr), Japanese (ja), Simplified Chinese (zh-hans), and Traditional Chinese (zh).

attributes Object No Session attributes. Can be combined with any start method. See the table below.
uiOptions Object No User interface options. Available only for Click-to-Chat sessions. See the table below.

Note: Only one of the properties marked as Exclusive – Start Method should be specified.

rep Properties

The rep object must have the following properties:

Name Type Required or Exclusive? Description
id Integer Required The representative's unique ID number. To get a representative's ID, see API Command: get_logged_in_reps.
name String Required The representative's public display name.

issue Properties

The issue object may be a JavaScript object with defined properties. Alternatively, it may be a DOM element, which should be a form. This DOM element must have one or more child inputs with defined names. If unnecessary elements are within the form, they will be ignored by the server. In either case, the accepted properties or input names are:

Name Type Required or Exclusive? Description
id Integer Exclusive – Issue Identifier The support issue's unique ID number. To get a list of issue IDs, see API Command: get_support_teams.
codeName String Exclusive – Issue Identifier The support issue's unique code name.

Note: Only one of the properties marked as Exclusive – Issue Identifier should be specified.

Note: The issue properties customerName, companyName, companyCode, and details have been deprecated as of 14.2 and have been replaced with the customer properties below. However, they are still available for backward compatibility.

customer Properties

The customer object has the following properties:

Name Type Required or Exclusive? Description
name String No The customer's name.
company String No The customer's company name.
company_code String No The customer's company code.
details String No A description of the customer's problem.

attributes Properties

The attributes object has the following properties:

Name Type Required or Exclusive? Description
external_key String No

The external key to associate with the session.

[custom field] String No The code name and value of any custom fields. These fields must first be configured in /login > Management > API Configuration.

Note: The attribute externalKey has been deprecated as of 14.2 and has been replaced with external_key. However, it is still available for backwards compatibility.

uiOptions Properties

The uiOptions object has the following property:

Name Type Required or Exclusive? Description
fallbackToFullWindow Boolean No Only used with click-to-chat sessions. If true, then a full-screen browser window will be used to render the click-to-chat client if a pop-up window cannot be created.

Collaborative Browser Sharing Functionality

Starting a collaborative browser sharing session using the API methods above will open a dialog box in the customer's browser, determine the optimal download method for this client, and initiate the download. If the Java applet is launched, then the dialog will automatically close once the download and execution are complete. In all other cases, the user should close the dialog by clicking outside of it. The experience will vary depending on which download mechanism JavaScript has determined will work best. One of four different displays will be shown:

  • Java applet download – A Java applet will launch, which will attempt to download and run the Bomgar customer client.
    • If the user has previously selected to remember the Bomgar customer client applet (even from another site), then the applet will launch with no prompts.
    • Otherwise, the user will be prompted to run the applet or to cancel.
      • If the user chooses to run the applet, then the applet will proceed to launch the customer client.
      • If the user chooses to cancels, the launch method will fall back to the JavaScript launch.
  • JavaScript launch – If the user does not have Java installed or if the user cancels the Java applet, the launch method will fall back to JavaScript.
    • JavaScript will tell the browser to download the Bomgar customer client, which will pop up a browser download dialog along with instructions for completing the download.
    • If the user cancels the JavaScript download dialog, the launch method will fall back to the manual launch.
  • Manual launch – If the user cancels all dialogs, he or she can click a link to re-trigger the download.
  • Mobile display – Because collaborative browser sharing is not currently supported on mobile devices, users will receive a message indicating that browser sharing is not available on mobile devices.

The Java applet requires Java 5+. Users who do not already have Java will not be prompted to download or install Java; the launch method will merely fall back to another download mechanism. If Java cannot be reliably detected, it will be assumed that Java is unavailable.

Click-to-Chat Without Using JavaScript

If you need to start a session with click-to-chat from an external site without writing any JavaScript, you may add the parameter c2cjs=1 to any of the documented start_session API URLs. This will cause the request to respond with a click-to-chat page instead of the full customer client download, regardless of the settings for the public site.

For example, to redirect the current page to start a click-to-chat session with a specific representative:

<a href="https://support.example.com/api/start_session?id=12&name=John&c2cjs=1">Chat with John</a>

To open click-to-chat for a specific representative in a new browser tab – not a new window – in most browsers:

<a href="https://support.example.com/api/start_session?id=12&name=John&c2cjs=1" target="_blank">Chat with John</a>

Please note that if you wish to open click-to-chat in a new, smaller browser window instead of the current window or a new browser tab, you must either use start_session.js or write your own JavaScript to create and correctly size the new window.

Note: For the sake of appearance, opening click-to-chat in an appropriately sized window is the recommended method. A window that is not properly sized will function correctly but will result in disproportionate margins.