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 Start Sessions with Click-To-Chat or Collaborative Browser Sharing.)

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

Note: The parameters customer_name, customer_company, customer_company_code, customer_desc, and external_key have been deprecated as of 14.2 and have been replaced with the parameters above. However, they are still available for backward compatibility.

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