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:

  1. By selecting a name from a list of logged-in representatives
  2. By entering a unique session key
  3. 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:

Session Generation by Representative Name and ID
id=[integer] The numeric ID for the representative with whom to start the session. To get a representative's ID, see API Command: get_logged_in_reps.
name=[string] The public display name for this same representative.
Session Generation by Session Key
short_key=[string] The seven-character string used to start a session.
Session Generation by Issue Submission Survey
issue_menu=[integer] Must be set to 1.
codeName=[string]

The code name of the selected issue.

Use either codeName or id, not both. If neither codeName nor id is specified, the session will go to the general queue if this queue is enabled.

id=[integer]

The numeric ID for the selected menu item. If Display Reps in Issues Menu is enabled from the Public Site Configuration page of the /login web interface, this will be the unique ID for a representative in the list. Otherwise, it will be the unique ID for an issue found in the issues list.

To get a representative's ID, see API Command: get_logged_in_reps. To get a list of valid issue IDs, see API Command: get_support_teams.

Use either codeName or id, not both. If neither codeName nor id is specified, the session will go to the general queue if this queue is enabled.

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

Optional Parameters

c2cjs=[integer] If set to 1, causes the session to start as a click-to-chat session. This method of starting a click-to-chat session is less preferred to using JavaScript. (See Use JavaScript to Start Click-To-Chat, Collaborative Browser Sharing, or Full Client Sessions.)

customer.name=[string]

Customer’s name (maximum of 100 characters).

customer.company=[string]

Customer’s company name (maximum of 100 characters).

customer.company_code=[string]

Customer’s company code (maximum of 100 characters).

customer.details=[string]

Customer’s problem description (maximum of 1024 characters).

locale=[string]

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).

platform=[string]

The specific Windows® platform (such as Windows 32-bit or 64-bit) for which to download the customer client. Use the correct parameters for the desired platform, winNT-32 or winNT-64.

session.custom.external_key=[string]

A key to an external help desk ticket system (maximum of 1024 characters).
session.custom.[custom field]=[string]

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

Each attribute must be specified as a different parameter. Each custom field has a maximum length of 1024 characters. The maximum total size of all combined custom fields, including the external key, must be limited to 10KB.

session.priority=[integer]

The priority of the session, from 1 to 3. 1 = high, 2 = medium, and 3 = low. The priority set by the API overrides the priority already set for the selected issue. If this parameter is not set by the API, the priority assigned to the selected issue will be used.

session.skills=[string] A comma-separated list of the code names of skills to assign to a session. The skills set by the API override the skills already set for the selected issue. If this parameter is not set by the API, the skills assigned to the selected issue will be used.
timezone_offset=[integer]

The difference in minutes between the client's local time and UTC. Positive values are east of the Prime Meridian, and negative values are west of the Prime Meridian.

This affects sessions routed through an Atlas cluster traffic node, where the cluster is configured to use the timezone offset method for choosing traffic nodes. The traffic node must have Accepting New Client Connections enabled. The master node redirects the client to the traffic node that is closest to the client's timezone. If multiple traffic nodes are equally close, then one is chosen at random. Clock skew between the master node and the traffic node must be less than two minutes.

This parameter is ignored if the appliance is not configured as above.

Note that if your Bomgar 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