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 support.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 they go to Site B, the session will be associated with Site B.

The command API is an authenticated API. For instructions on using authenticated APIs using OAuth, see Authenticate to the Remote Support API. The API account must have full access to the command API.

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.

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


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

The queue in which this session will be placed. This value 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. This is static text defined by Bomgar and is not configurable.
<mail_body> The body of the session key email invitation. This is static text defined by Bomgar and is not configurable.

Query Examples: generate_session_key

General queue
  • https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=general
Specific representative by ID
  • https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=rep:1
Specific team
  • https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=team:1
Specific embassy
  • https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=embassy:1
Specific representative by username
  • https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=rep_username:admin
Specific issue
  • https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=issue:other
General queue, 1 hour time to live
  • https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=general&ttl=3600
General queue, external key and custom field
  • https://support.example.com/api/command?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?action=generate_session_key&type=support&queue_id=general&url_hostname=support.example.com
General queue, skills and priority set
  • https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=general&session.priority=1&session.skills=codename1,codename2