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.

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.

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.