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:
| 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. |
| short_key=[string] | The seven-character string used to start a session. |
| issue_menu=[integer] | Must be set to 1. |
| codeName=[string] |
The code name of the selected issue. Use either codeName or id, not both. |
| 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. |
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 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 bytes). The number of characters varies depending on the language and character set used for the public portal. If in doubt, you can use one of the available online character byte count tools to help you determine your character limit. |
|
locale=[string] |
The locale code of the language to be used for this customer client. The language must be installed on your B Series Appliance. 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). |
| chat_locale | The chat_locale parameter can be used to set the chat locale to a language that is supported by GeoFluent but is not supported by BeyondTrust. Example: https://support.example.com/api/start_session?short_key=2962035&locale=en-us&chat_locale=cs-cs. |
| 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 primary 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 primary node and the traffic node must be less than two minutes. This parameter is ignored if the B Series Appliance is not configured as above. |
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 |
