Use JavaScript to Start Click-To-Chat, Collaborative Browser Sharing, or Full Client Sessions

To start a session using JavaScript, 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, BG.START_TYPE.BROWSER, or BG.START_TYPE.FULL. 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. Each of the sessions below can be called as any of the three session types by changing the start type to BG.START_TYPE.CHAT, BG.START_TYPE.BROWSER, or BG.START_TYPE.FULL.

Starting a Full Client Session with a Session Key

BG.start(BG.START_TYPE.FULL, {

sessionKey: '1728331'

});

Starting a Full Client Session with Representative Information

BG.start(BG.START_TYPE.FULL, {

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>

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), Finnish (fi), 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.

Full Client or Collaborative Browser Sharing Functionality

Starting a full client session or a collaborative browser sharing session using the API methods above opens a dialog box in the customer's browser, determines the optimal download method for this client, and initiates the download. The experience varies depending on which download mechanism JavaScript has determined will work best. One of five different displays is shown:

  • ClickOnce – A session started in Internet Explorer uses the ClickOnce technology to attempt to download and run the Bomgar customer client.
  • Java applet download – A Java applet launches, which attempts 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 launches with no prompts.
    • Otherwise, the user is prompted to run the applet or to cancel.
      • If the user chooses to run the applet, then the applet proceeds to launch the customer client.
      • If the user chooses to cancel, the launch method falls back to the JavaScript launch.

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

  • JavaScript launch – If the user does not have Java installed or if the user cancels the Java applet, the launch method falls back to JavaScript.
    • JavaScript tells the browser to download the Bomgar customer client, which pops up a browser download dialog along with instructions for completing the download.
    • If the user cancels the JavaScript download dialog, the launch method falls 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 – Behavior varies on the type of session being requested.
    • For a full-client session, the device is searched for the Bomgar customer client app.
      • If the app is already installed, the app opens, and the session automatically begins.
      • If the app is not installed, a browser dialog provides a link to install the Bomgar customer client app from the device's app store. Once the app is installed, the second link in the browser dialog provides a method to start the session.
    • Because collaborative browser sharing is not currently supported on mobile devices, mobile users receive a message indicating that browser sharing is not available.

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.