API Command: generate_session_key

The generate_session_key command creates a new session key to be used in starting a support session. Note that if your Bomgar Appliance has multiple public sites, the session key created may be associated with any of these sites, depending on the method used to download the customer client.

For example, Site A has a hostname of support.example.com, and Site B has a hostname of remote. example. com. When a generate_session_key request is made to support.example.com with a url_hostname of remote.example.com, both a session key code and a unique session key URL will be generated.

If the customer goes to the generated URL to download the customer client, then the session will be associated with Site B, because the session key URL points to the hostname designated by the url_hostname parameter.

However, the customer could also download the customer client by submitting the session key code on either site. Therefore, if the customer goes to Site A to submit the code, then the session will be associated with Site A, while if he or she goes to Site B, the session will be associated with Site B.

In order to issue the generate_session_key command, you will need to supply the username and password for a Bomgar user account. That account must have the permission Allowed to Use Command API along with the permission Allowed to Provide Remote Support.

Required Parameters for generate_session_key

type=[string] The type of session for which you would like to generate a session key. Currently, the only supported value is support.
queue_id=[string]

The queue in which the session should be placed. Can be one of general, rep:[id], team:[id], or embassy:[id], where [id] is the numeric ID for the representative, team, or Embassy queue in which you wish to place this session.

Can also be rep_username:[username]. This call will work only if a single user with the given username exists; otherwise, an error message will be returned.

Can also be issue:[issue_code_name].

To get a representative's ID, see API Command: get_logged_in_reps. To get a team's ID, see API Command: get_support_teams.

Optional Parameters for generate_session_key

session.custom.external_key=[string]

An arbitrary string that can link this session to an identifier on an external system, such as a help desk ticket ID. This has a maximum length 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.
session.skills=[string] A comma-separated list of the code names of skills to assign to a session.
ttl=[integer] Time in seconds for which this key should be valid. If omitted, the maximum session key timeout set in the administrative interface will be used.
url_hostname=[string] Hostname to use in the URL generated for the session key. Defaults to the primary hostname for your Bomgar Appliance.

Note: The parameter external_key has been deprecated as of 14.2 and has been replaced with session.custom.external_key. However, it is still available for backward compatibility.

Note: If a parameter is set via generate_session_key and is then overwritten via another API (e.g., start_session) then the second attribute will take precedence.

XML Response for generate_session_key Query

<type> The type of session for which this key was generated. Currently, the only supported value is support.
<ttl> Time in seconds for which this key is valid.
<expires> The timestamp at which this session key expires.
<queue>

The queue in which this session will be placed. Will be general, rep, team or embassy.

Also contains an available attribute. For a session key targeting a representative, the value is 1 if that representative is logged in. For a session key targeting a team, embassy, or general queue, the value is 1 if at least one representative is logged in for that queue or the queue is persistent. If no representative is available for the targeted queue, the value is 0.

<queue_id> The numeric ID of the queue.
<external_key> A string that links this session to an identifier on an external system, such as a help desk ticket ID.
<short_key> The seven-character string that the customer can enter on your public site to start a session.
<key_url> The session key url to which the customer can go to start a session.
<mail_subject> The subject line of the session key email invitation.
<mail_body> The body of the session key email invitation.

Query Examples: generate_session_key

General queue https://support.example.com/api/command?username=test&password=test&action=generate_session_key&type=support&queue_id=general
Specific representative by ID https://support.example.com/api/command?username=test&password=test&action=generate_session_key&type=support&queue_id=rep:1
Specific team https://support.example.com/api/command?username=test&password=test&action=generate_session_key&type=support&queue_id=team:1
Specific Embassy https://support.example.com/api/command?username=test&password=test&action=generate_session_key&type=support&queue_id=embassy:1
Specific representative by username https://support.example.com/api/command?username=test&password=test&action=generate_session_key&type=support&queue_id=rep_username:admin
Specific issue https://support.example.com/api/command?username=test&password=test&action=generate_session_key&type=support&queue_id=issue:other
General queue, 1 hour time to live https://support.example.com/api/command?username=test&password=test&action=generate_session_key&type=support&queue_id=general&ttl=3600
General queue, external key and custom field https://support.example.com/api/command?username=test&password=test&action=generate_session_key&type=support&queue_id=general&session.custom.external_key=ABC1234&session.custom.custom_field1=Custom%20Value
General queue, specific Hostname https://support.example.com/api/command?username=test&password=test&action=generate_session_key&type=support&queue_id=general&url_hostname=remote.example.com
General queue, skills and priority set https://support.example.com/api/command?username=test&password=test&action=generate_session_key&type=support&queue_id=general&session.priority=1&session.skills=codename1,codename2