Use JavaScript to start click-to-chat or full client sessions
To start a session using JavaScript, you must first reference an external JavaScript file that is included on your BeyondTrust Appliance B Series. 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.FULL. This determines which type of session is launched. The options parameter expects a generic JavaScript object which contains set properties.
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.
start_session.js will not work with public portals that require SAML authentication. This is due to issues with Cross-Origin Resource Sharing (CORS).
For more information, please see options properties.
Script examples
Several common examples are listed below, though more are possible. Each of the sessions below can be called either of the session types by changing the start type to BG.START_TYPE.CHAT 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 full client session with a session key and custom fields
BG.start(BG.START_TYPE.FULL, { sessionKey: '8679485', attributes: { external_key: 'abc123', custom_field1: 'Custom Value', custom_field2: 123 } });
Starting a full client session with a session key and a specified language
BG.start(BG.START_TYPE.FULL, { sessionKey: '8679485', locale: 'en-us' });
Starting a full client session with an issue object (by ID) and customer information
BG.start(BG.START_TYPE.FULL, { issue: { id: 12 }, customer: { name: 'Customer Name', company: 'Company Name', company_code: 'Company Code', details: 'Issue Details' } });
Starting a full client session with an issue object (by code name) and skills
BG.start(BG.START_TYPE.FULL, { issue: { codeName: 'Other' } skills: ["skill1", "skill2"] });
Starting a full client session with an issue form element
BG.start(BG.START_TYPE.FULL, { 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 BeyondTrust Appliance B Series. To see which languages are installed, go to /login > Localization > Languages. Available language packages can 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), Traditional Chinese (zh), and Russian (ru). |
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. |
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. |
Only one of the properties marked as Exclusive - Issue Identifier should be specified. |
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. |
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 functionality
Starting a 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 BeyondTrust customer client.
- JavaScript launch - If the user does not have ClickOnce support or if the user cancels the ClickOnce prompt, the launch method falls back to JavaScript.
- JavaScript tells the browser to download the BeyondTrust 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, they 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 BeyondTrust 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 BeyondTrust 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.
- For a full-client session, the device is searched for the BeyondTrust customer client app.
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" rel="noreferrer noopener">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.
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.