Session generation API

The public site is a collection of forms and links which generates an HTTP request each time a session is requested, resulting in the customer client’s being downloaded to the remote computer. The request generated depends on the configuration of the public site and the method used by the customer to request support:

• By selecting a name from a list of logged-in representatives
• By entering a unique session key
• By submitting an issue

The session generation API URL is https://support.example.com/api/start_session

The queue in which to place the customer after connecting can be specified in one of three ways:

You may also add optional parameters to pass additional information to the session.

Optional parameters

Note that if your B Series Appliance has multiple public sites, the session created will be associated with the public site whose domain name matches the request’s domain name. For example, if Site A has a hostname of support.example.com and Site B has a hostname of support.example.com, a session generation request made to support.example.com will create a session associated with Site A.

Also note the session key behavior if the option to prompt customers before downloading the customer client is enabled from /login > Public Portals > Public Sites. If prompting is enabled, then only the external key can be passed along with the session key. If the prompt is disabled, you can include other parameters with the session key.

Query examples

• Specific representative

https://support.example.com/api/start_session?id=1&name=Admin

• Session key

https://support.example.com/api/start_session?short_key=1234567&session.custom.external_key=1234

• Issue submission survey using issue ID

https://support.example.com/api/start_session?issue_menu=1&customer.name=John%20Doe&customer.company=Company%20Name&customer.company_code=1234&customer.details=I%20need%20support&id=1&session.custom.external_key=1234&session.custom.custom_field1=Custom%20Value

• Issue submission survey using issue code name

https://support.example.com/api/start_session?issue_menu=1&customer.name=John%20Doe&customer.company=Company%20Name&customer.company_code=1234&customer.details=I%20need%20support&codeName=issue_code_name&session.custom.external_key=1234&session.custom.custom_field1=Custom%20Value

• Issue submission survey using ID, with skills and priority

https://support.example.com/api/start_session?issue_menu=1&customer.name=John%20Doe&customer.company=Company%20Name&customer.details=I%20need%20support&id=1&session.priority=1&session.skills=codename1,codename2

• Locale

https://support.example.com/api/start_session?id=1&name=Admin&locale=en-us

• Platform

https://support.example.com/api/start_session?id=1&name=Admin&platform=winNT-32

• Timezone Offset

https://support.example.com/api/start_session?id=1&name=Admin&timezone_offset=-300

Session key acceptance

An alternative method of starting a session is to create a web form where your customers can enter short session key strings to start sessions with you.

To create a session key entry form, create a web form with the action of https://support.example.com/api/start_session and a method of either GET or POST. You must also use a text box with the name of short_key, as shown in the example below.

<form action="https://support.example.com/api/start_session" method="get">
	Session Key: <input type="text" name="short_key" /><br />
		<input type="submit" value="Submit" />
</form>

You may also include an external key to start a session.

<form action="https://support.example.com/api/start_session" method="get">
	Session Key: <input type="text" name="short_key" /><br />
	External Key: <input type="text" name="session.custom.external_key" /><br />
		<input type="submit" value="Submit" />
</form>

Using this form, your customer can enter a generated seven-character session key and an optional external key to start a session with you.

Start a session

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.

⚠️

Important

Your HTML page must have a valid standards-compliant Doctype. View recommended Doctype declarations.

ℹ️

Note

start_session.js will not work with public portals that require SAML authentication. This is due to issues with Cross-Origin Resource Sharing (CORS).

ℹ️

Note

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'
});

ℹ️

Note

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:

📘

Note

Only one of the properties marked as Exclusive - Start Method should be specified.

rep properties

The rep object must have the following properties:

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:

customer properties

The customer object has the following properties:

attributes properties

The attributes object has the following properties:

uiOptions properties

The uiOptions object has the following property:

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.

ℹ️

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.

External keys (TicketID)

The external key is a text string sent to the B Series Appliance to be logged as a property of a particular support session. This key typically originates from software separate from the BeyondTrust software. It does not need to be a unique value but usually is. The external key can be specified in one of two ways.

Manual entry

The support representative who has ownership of a BeyondTrust session can manually assign a key value from within the representative console. The summary pane of a session displays that session’s external key. Click the Edit External Key button to modify this value. You can edit the external key from either the Session Info tab or the Custom Info tab. Editing the external key in one location will change it in both.

Programmatic assignment

The second, more useful way of designating an external key is from within the URL sent to the B Series Appliance by the customer client. The external key can be specified with any of the session start methods documented above, as well as with the generate_session_key command detailed below.

The issue submission survey generates an HTTP request similar in format to the following example:

https://support.example.com/api/start_session?issue_menu=1&customer.name=John%20Doe&customer.company=Company%20Name&customer.company_code=1234&customer.details=I%20need%20support&id=1&session.custom.external_key=1234

Note the session.custom.external_key parameter specified in the sample request provided. If an external key is specified in this manner, the representative console will automatically populate its external key field with the given value.

The API allows creation of a custom web site or application that can be used instead of the public site to establish a support session. Code within this custom software must generate HTTP requests in the format displayed in the example above to initiate the session and pre-populate the external key within the representative console.

Using the external key

Once a support session has an external key associated with it, you can use the reporting API to generate XML session data containing the external key. This provides the means for middleware to be developed to provide a relationship between the reporting data used by BeyondTrust and the correlating ticketing system’s ticket numbers.

Embedded Support Button

Define custom links within your in-house developed applications to call a pre-installed Support Button. An embedded Support Button gives support providers the ability to streamline the support path for specific applications.

The command line options can leverage the same session initiation methods as configured in the Support Button profile, or they can bypass the user interface altogether. You can configure this embedded Support Button to point to a specific issue so that when a customer clicks the button, a session will immediately start with the team best suited to handle that type of problem. The command also can assign an external key to sessions started from this embedded Support Button.

To create an embedded Support Button, a Support Button must first be deployed on the remote system. You may wish to define the Support Button profile so that neither the desktop shortcut nor the menu shortcut is created. Because a Support Button must be pre-installed, using an embedded Support Button prevents users from having to download the customer client each time they request support. Embedded Support Buttons are a Windows-only feature.

To start an embedded Support Button programmatically, first open the registry editor and locate the Support Button registry entry. Then copy the value data. The registry entry can be found in one of two places:

• Single User Install: HKEY_CURRENT_USER\Software\Bomgar\CallbackButton\<site_name>\cb-install-cmdline
• All Users Install: HKEY_LOCAL_MACHINE\Software\Bomgar\CallbackButton\<site_name>\cb-install-cmdline

After pasting the value data into a text editor or the command prompt, add optional arguments.

Finally, run the command line.

Example:

C:\Users\admin\AppData\Local\bomgar-scc-cb\support.example.com\bomgar-cb-w0dc30ji8hz65yji8hz65yji8hz65yji8hz65yc40ic90.exe --cbdir C:\Users\admin\AppData\Local\bomgar-scc-cb\support.example.com\ --session-value session.custom.external_key "abc123" --issue-code-name install_update --present-front-end-survey

ℹ️

Note

The command line option --cbdir <support_button_install_directory> is required.

ℹ️

Note

This feature is not supported for ARM-based Windows systems.