Command API
The command API is designed to send commands to your BeyondTrust site from an outside application. Commands can start or transfer a support session, get a list of logged-in representatives, or obtain a list of support teams and issues. You can also check the health of your B Series Appliance, change a B Series Appliance's failover role, or get information about your BeyondTrust API version.
Commands are executed by sending an HTTP request to the B Series Appliance. Send the request using any HTTPS-capable socket library, scripting language module, or URL fetcher such as cURL or wget. Use either GET or POST as the request method.
POST requests must include a "Content-Type: application/x-www-form-urlencoded" HTTP header when supplying parameters in the request body, and the parameters must be url-encoded. Multipart POST requests are not supported.
Important
When making consecutive API calls, you must close the connection after each API call.
The command API URL is https://support.example.com/api/command.
An XML schema describing the command API response format is available at https://support.example.com/api/command.xsd.
Note
The command API is an authenticated API. The API account must have read-only or full access to the command API.
For instructions on using authenticated APIs using OAuth, see Authenticate to the API.
Required parameters for the command API
| action=[string] |
The type of action to perform. Can be any of the following: |
Important
If you experience a high volume of support requests, repeatedly calling a command such as get_logged_in_reps or get_support_teams might bottleneck your system. Therefore, a best practice is to not request a list of representatives or teams with each support request. Instead, if making the same API call in succession, consider caching the results for a period of time and reusing them. New sessions requests should reference the cached list instead of calling for the list each time.
The command API returns XML responses that declare a namespace. If you are parsing these responses with a namespace-aware parser, you need to set the namespace appropriately or ignore the namespace while parsing the XML:
Command API: https://support.example.com/namespaces/API/command
Note
The above namespace is returned XML data and is not a functional URL.
check_health
The check_health command returns XML data containing information about the B Series Appliance, specifically including information needed for failover purposes.
XML response for check_health query
| <appliance> | The hostname of the B Series Appliance. Also contains an id attribute that contains the B Series Appliance's GUID. |
| <version> | The version number and build number of the BeyondTrust software running on the B Series Appliance. |
| <success> | Integer value (1 or 0) indicating if the health check of the B Series Appliance was successful. |
| <error_message> | Returns an error message if a problem is found. If no error is found, this element will not be returned. |
| <failover_role> | The role the B Series Appliance plays in the failover relationship. Can be one of none (if failover is not configured), primary, or backup. |
| <enabled_shared_ips> | Contains an <ip> element for each IP address which is shared between the primary and backup B Series Appliances. If no shared IP addresses are enabled, this element will not be returned. |
| <last_data_sync_time> | The date and time at which the last data sync occurred between the primary and backup B Series Appliances. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the data sync time as a UNIX timestamp (UTC). |
| <last_data_sync_status> | Contains a string showing the status of the last data sync. |
Query example: check_health
https://support.example.com/api/command?action=check_health
Alternative method - HTTP status check
As an addition or alternative to using the API command above, you can use https://support.example.com/check_health to check the health of a B Series Appliance. This returns an HTTP status of 200 if the probe is successful and 500 (Server Error) if not. While you will see a simple human-readable message showing success or failure, no other data is exposed.
create_virtual_customer
The create_virtual_customer request creates a virtual customer in Remote Support and places that customer in a new session. This operation is necessary so that Remote Support can accurately display and log chat messages forwarded by the chat bot on behalf of the end user. Before calling this API, integrations must use the generate_session_key operation to get a 7 digit short key to start a session.
Required parameters for create_virtual_customer
| short_key | The short_key returned from the generate_session_key operation. |
| ip_address | The public IP address of the customer. |
| operating_system | The operating system of the customer. |
| computer_name | The computer name to be shown with the customer. |
Optional parameter for create_virtual_customer
| locale=[string] | The locale code of the language to be used for this chat bot. 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). |
XML response for create_virtual_customer query
| download_url | The URL from which the native customer client can be downloaded to elevate from a virtual chat-only customer to a non-virtual full remote support session. |
| chat_url | If this parameter is set to 1, then the download_url returned redirects to a click-to-chat (c2c) session. If it is omitted or given any other value, then download_url returns a URL to download the full client (this is the current behavior). |
Query examples: create_virtual_customer
https://support.example.com/api/command?action=: create_virtual_customer
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 B Series 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.
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], or team:[id], where [id] is the numeric ID for the representative, or team 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 get_logged_in_reps. To get a team's ID, see 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 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 B Series 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. |
| <queue> | The queue in which this session will be placed. This value will be rep or team. 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, 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 BeyondTrust and is not configurable. |
| <mail_body> | The body of the session key email invitation. This is static text defined by BeyondTrust and is not configurable. |
Query examples: generate_session_key
- 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 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
- Specific team, 1 hour time to live
https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=team:1&ttl=3600
- Specific team, external key and custom field
https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=team:1&session.custom.external_key=ABC1234&session.custom.custom_field1=Custom%20Value
- Specific team, specific hostname
https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=team:1&url_hostname=support.example.com
- Specific team, skills and priority set
https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=team:1&session.priority=1&session.skills=codename1,codename2"
get_api_info
The get_api_info request returns XML data containing the current API version information.
XML response for get_api_info query
| <api_version> | The software version of the current BeyondTrust API. |
| <timestamp> | The server’s current timestamp at the time this report was pulled. |
| <permissions> | The permissions of the API account used to issue this command. The permissions shown are detailed below. |
Element names and attributes
/get_api_info/permissions/permission
| perm_backup | Integer value (1 or 0) indicating if the API account has permission to use the backup API. |
| perm_command | String indicating if the API account has full access to the command API, read_only access, or no access (deny). |
| perm_configuration | Integer value (1 or 0) indicating if the API account has permission to use the Configuration API. |
| perm_configuration_vault_account | Integer value (1 or 0) indicating if the API account has permission to manage Vault accounts via the Configuration API. |
| perm_ecm | Integer value (1 or 0) indicating if the API account can be used by an Endpoint Credential Manager client to connect to the appliance. |
| perm_real_time_state | Integer value (1 or 0) indicating if the API account has permission to use the Real-Time State API. |
| perm_reporting_archive | Integer value (1 or 0) indicating if the API account has permission to use the archive reporting API. |
| perm_reporting_license | Integer value (1 or 0) indicating if the API account has permission to use the license usage reporting API. |
| perm_reporting_support | Integer value (1 or 0) indicating if the API account has permission to use the support session reporting API. |
| perm_reporting_vault | Integer value (1 or 0) indicating if the API account has permission to run Vault Activity reports. |
| perm_vault_backup | Integer value (1 or 0) indicating if the API account has permission to backup the Vault encryption key, the key used to encrypt and decrypt all the Vault credentials stored on the appliance. |
Query example: get_api_info
https://support.example.com/api/command?action=get_api_info
get_appliances
The get_appliances command returns XML data containing all configured B Series Appliances in a failover relationship or cluster.
XML response for get_appliances
| <appliances> | Contains an <appliance> element for each connected B Series Appliance. If an error occurs, it will contain an <error> element describing the problem. |
Element names and attributes
/appliances/appliance
| id (attribute) | The B Series Appliance's GUID. |
| <name> | The name of the B Series Appliance. |
| <public_hostname> | The public hostname of the B Series Appliance. |
| <cluster_role> | The role the B Series Appliance plays in a cluster. Can be one of single (if not part of a cluster), primary, or traffic. |
| <failover_role> | The role the B Series Appliance plays in a failover relationship. Can be one of none (if failover is not configured), primary, or backup. |
| <accepting_connections> | Integer value (1 or 0) indicating if this B Series Appliance accepts new client connections. If not part of a cluster, this will always be 1. |
| <timezone_offset> | The number of seconds away from UTC. |
Query example: get_appliances
https://support.example.com/api/command?action=get_appliances
get_connected_clients
The get_connected_clients command returns XML data containing details of all connected BeyondTrust clients.
Required parameters for get_connected_clients
| type=[string] | The types of clients to return in the results. Can be a comma-separated list of values. Supported values are all (default), representative, support_customer, and push_agent. |
| id=[string] | The ID of the client. To get client IDs, see get_connected_client_list. Can be a comma-separated list of values. A maximum of 100 IDs is supported. This ID is a unique identifier which remains valid only while the client is connected. |
| include_connections=[boolean] | If this is set to 1, then the client's list of connections to B Series Appliances and an event log about those connections will be included in the results. |
XML response for get_connected_clients
| <connected_clients> | Contains a child element for each connected client, including <connected_representative>, <connected_support_customer>, and <connected_push_agent>. |
Element names and attributes
/connected_clients/connected_representative
| id (attribute) | A unique identifier which remains valid only while the client is connected. |
| <client_connections> | Contains a <client_connections> element and an <event_log> element. This element is returned only if the query specifies include_connections. |
| <hostname> | The hostname of the representative’s computer. |
| <platform> | The operating system of the representative’s computer. Also contains an id attribute that briefly notes the selected platform for the client. |
| <timezone_offset> | The number of seconds away from UTC. |
| <connected_since> | The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections. |
| <user_id> | Unique ID assigned to the representative. |
| <type> | The type of account the representative is using. Can be one of Normal or Invited. |
| <username> | The username assigned to the representative. |
| <public_display_name> | The public display name assigned to the representative. Note that this field contains the public display name's value at the time of the conference, which may not match the current value if the public_display_name has subsequently been changed. |
| <private_display_name> | The private display name assigned to the representative. Note that this field contains the private display name's value at the time of the conference, which may not match the current value if the private_display_name has subsequently been changed. |
| <start_session_url> | A URL that can be sent to a customer to start a support session with the representative. |
| <support_session_count> | The number of sessions the representative is participating in. |
| <showing_on_rep_list> | Integer value (1 or 0) indicating if the representative appears in the representative list on the public site. |
| <routing_idle> | Integer value (1 or 0) indicating if the representative has a status of idle. |
| <routing_busy> | Integer value (1 or 0) indicating if the representative has a status of busy. |
| <routing_enabled> | Integer value (1 or 0) indicating if the representative has automatic session assignment enabled or disabled. |
| <routing_available> | Integer value (1 or 0) indicating if the representative is available to have sessions automatically assigned. |
| <support_license> | The type of license used by the representative. |
| <support_session_lsids> | Contains an <lsid> element for each session in which the representative is participating. This field corresponds with the <lsid> field of the <connected_support_customer> element. |
/connected_clients/connected_support_customer
| id (attribute) | A unique identifier which remains valid only while the client is connected. |
| <client_connections> | Contains a <client_connections> element and an <event_log> element. This element is returned only if the query specifies include_connections. |
| <hostname> | The hostname of the customer’s computer. |
| <platform> | The operating system of the customer’s computer. Also contains an id attribute that briefly notes the selected platform for the client. |
| <timezone_offset> | The number of seconds away from UTC. |
| <connected_since> | The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections. |
| <name> | The name which the customer entered in the Your Name field of the front-end survey or which was assigned programmatically. |
| <non_interactive> | Indicates if the session is a remote desktop protocol (RDP) session or a Shell Jump session. Can be either rdp or shelljump. If neither, this element is not returned. |
| <lsid> | A string which uniquely identifies this session. This field corresponds with the field of the <connected_representative> element. |
/connected_clients/connected_push_agent
| id (attribute) | A unique identifier which remains valid only while the client is connected. |
| <client_connections> | Contains a <client_connection> element and an <event_log> element. This element is returned only if the query specifies include_connections. |
| <hostname> | The hostname of the Jumpoint’s host computer. |
| <platform> | The operating system of the Jumpoint’s host computer. Also contains an id attribute that briefly notes the selected platform for the client. |
| <timezone_offset> | The number of seconds away from UTC. |
| <connected_since> | The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections. |
| <name> | The Jumpoint's name. |
/client_connection
| <appliance_id> | The GUID of the B Series Appliance to which the client is connected. |
| <purpose> | The reason the representative is connected to this B Series Appliance. Can be either primary or traffic. If not part of a cluster, this will always be primary. |
| <receive_traffic_node> | Integer value (1 or 0) indicating whether this is the client's default traffic node or not. If not part of a cluster, this will always be 0. |
| <connected_since> | The date and time at which the client connected. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). |
| <private_ip> | The client's private IP address that was used to connect to the B Series Appliance. |
/event_log
| <event> | An <event> element is created for each event that took place during this connection. Up to the last 20 events are returned. Events detail when and why a client connected to a B Series Appliance. Events also include failures to connect to nodes and normal disconnects. Includes a ts attribute which displays the timestamp of the event. |
Query examples: get_connected_clients
- Get a detailed list of all connected clients
https://support.example.com/api/command?action=get_connected_clients
- Get a detailed list of all connected representatives
https://support.example.com/api/command?action=get_connected_clients&type=representative
- Get a detailed list of all connected representatives and support customers
https://support.example.com/api/command?action=get_connected_clients&type=representative,support_customer
- Get a detailed list of all clients with IDs 101, 102, and 103
https://support.example.com/api/command?action=get_connected_clients&id=101,102,103
- Get a detailed list of all clients with IDs 101, 102, and 103 AND whose type is representative or customer
https://support.example.com/api/command?action=get_connected_clients&id=101,102,103&type=representative,support_customer
- Get a detailed list, with connection information, of all connected clients
https://support.example.com/api/command?action=get_connected_clients&include_connections=1
- Get a detailed list, with connection information, of all connected representatives
https://support.example.com/api/command?action=get_connected_clients&type=representative&include_connections=1
- Get a detailed list, with connection information, of all connected representatives and support customers
https://support.example.com/api/command?action=get_connected_clients&type=representative,support_customer&include_connections=1
- Get a detailed list, with connection information, of all clients with IDs 101, 102, and 103
https://support.example.com/api/command?action=get_connected_clients&id=101,102,103&include_connections=1
- Get a detailed list, with connection information, of all clients with IDs 101, 102, and 103 AND whose type is representative or customer
https://support.example.com/api/command?action=get_connected_clients&id=101,102,103&type=representative,support_customer&include_connections=1
get_connected_client_list
The get_connected_client_list command returns XML data containing a summary or list of all connected BeyondTrust clients.
Optional parameters for get_connected_client_list
| type=[string] | The types of clients to return in the results. Can be a comma-separated list of values. Supported values are all (default), representative, support_customer, and push_agent. Currently, pinned_client is not a possible value. If the count of pinned Jump Clients is needed in the summary, then all must be specified. |
| summary_only=[boolean] | To return only a summary, set this to 1. |
XML response for get_connected_client_list
| <connected_client_list> | Contains a <connected_client_summary> element with a summary of the data. Also contains a <connected_client> element for each client currently connected to the B Series Appliance. If an error occurs, it will contain an <error> element describing the problem. |
Element names and attributes
/connected_client_list/connected_client_summary
| <appliance_summary> | An <appliance_summary> element is created for each connected B Series Appliance. |
/connected_client_list/connected_client_summary/appliance_summary
| id (attribute) | The B Series Appliance's GUID. |
| <count> | A <count> element is created for each type of client connected to this B Series Appliance. |
/connected_client_list/connected_client_summary/appliance_summary/count
| type (attribute) | The type of client connected to the B Series Appliance. Can be one of representative, support_customer, push_agent, or pinned_client. |
/connected_client_list/connected_client
| type (attribute) | The type of client connected to one of the clustered B Series Appliances. Can be one of representative, support_customer, or push_agent. |
| id (attribute) | A unique identifier which remains valid only while the client is connected. |
Query examples: get_connected_client_list
- Get a list of all connected clients
https://support.example.com/api/command?action=get_connected_client_list
- Get a list of all connected representatives
https://support.example.com/api/command?action=get_connected_client_list&type=representative
- Get a list of all connected representatives and support customers
https://support.example.com/api/command?action=get_connected_client_list&type=representative,support_customer
- Get a summary of all connected clients
https://support.example.com/api/command?action=get_connected_client_list&summary_only=1
- Get a summary of all connected representatives
https://support.example.com/api/command?action=get_connected_client_list&summary_only=1&type=representative
- Get a summary of all connected representatives and support customers
https://support.example.com/api/command?action=get_connected_client_list&summary_only=1&type=representative,support_customer
get_logged_in_reps
The get_logged_in_reps request returns XML data about all logged-in representatives. It requires no additional parameters.
XML response for get_logged_in_reps Query
| <logged_in_reps> | Returns a <rep> element for each logged-in representative. If no representatives are logged in, this element will contain no <rep> elements. If an error occurs, it will contain an <error> element describing the problem. |
Element names and attributes
/logged_in_reps/rep
| id (attribute) | Unique ID assigned to the representative. |
| <display_name> | This element is deprecated as of API version 1.10.0 but still exists for backwards compatibility. Its value is the same as that of <public_display_name>. |
| <public_display_name> | The public display name currently assigned to the representative. |
| <private_display_name> | The private display name currently assigned to the representative. |
| The type of rep logged in. Types include Normal and Invited. | |
| <direct_link> | An HTML anchor tag containing the URL that customers can use to download the customer client to connect directly to the representative. |
| <logged_in_since> | The date and time at which the representative logged in. |
| <support_session_count> | The number of active sessions the representative is currently running. |
| <showing_on_rep_list> | Integer value (1 or 0) indicating if the rep has permission to show on the public site and has the Showing On Representative List option checked in the representative console. |
Query example: get_logged_in_reps
https://support.example.com/api/command?action=get_logged_in_reps
get_session_attributes
The get_session_attributes command returns attributes set for an active support session.
Required parameter for get_session_attributes
| lsid=[string] | The ID of the session whose attributes you wish to get. The session must currently be active. |
XML response for get_session_attributes query
| <custom_attributes> | Contains a <custom_attribute> element for each custom attribute set for the session. |
| <error> | Returns an error message if the attributes were not retrieved successfully. |
Element names and attributes
/custom_attributes/custom_attribute
| display_name (attribute) | The display name assigned to the custom attribute. |
| code_name (attribute) | The code name assigned to the custom attribute. |
Query example: get_session_attributes
- Get custom attributes for session c69a8e10bea9428f816cfababe9815fe
https://support.example.com/api/command?action=get_session_attributes&lsid=c69a8e10bea9428f816cfababe9815fe
get_support_teams
The get_support_teams request returns XML data containing all configured support teams and all the issues configured for each team.
Optional parameter for get_support_teams
| showmembers=1 | Causes the output to also list all the representatives who are members of each team. Depending on team configuration, showing all members could add a significant amount of data to the output and should be used sparingly. |
XML response for get_support_teams query
| <support_teams> | Contains a <support_team> element for each support team. If no support teams have been created, this element will contain no <support_team> elements. If an error occurs, it will contain an <error> element describing the problem. |
Element names and attributes
/support_teams/support_team
| id (attribute) | Unique ID assigned to the support team. |
| <name> | The name of the support team. |
| <issues> | Contains an <issue> element for each issue associated with this support team, as described below. If no issues have been configured for this team, the <issue> element will be blank. |
| <support_session_count> | The number of sessions waiting in this team queue. |
| <members> | Displayed only if the showmembers parameter has been included in the request. Contains a <representative> element for each member of this team. If no representatives have been assigned to this team, the <members> element will be blank. |
/support_teams/support_team/issues/issue
| id (attribute) | Unique ID assigned to this issue. |
| The title of the issue. |
/support_teams/support_team/members/representative
| id (attribute) | Unique ID assigned to the representative. |
| <username> | The username assigned to the representative. |
| <display_name> | This element is deprecated as of API version 1.10.0 but still exists for backwards compatibility. Its value is the same as that of <public_display_name>. |
| <public_display_name> | The public display name currently assigned to the representative. |
| <private_display_name> | The private display name currently assigned to the representative. |
Query examples: get_support_teams
- Show names and issues
https://support.example.com/api/command?action=get_support_teams
- Show names, issues, and members
https://support.example.com/api/command?action=get_support_teams&showmembers=1
import_jump_shortcut
The import_jump_shortcut command creates a Jump shortcut. When dealing with a large number of Jump shortcuts, it may be easier to import them programmatically than to add them one by one in the representative console.
Required parameters for import_jump_shortcut - Local Jump
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| local_jump_hostname=[string] | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
| group=[string] | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcut - Local Jump
| tag=[string] | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments=[string] | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy=[string] | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
| session_policy=[string] | The code name of a session policy. You can specify a session policy to manage the permissions available on this Jump Item. |
| public_portal=[string] | The public portal through which this Jump Item should connect. |
Required parameters for import_jump_shortcut - Remote Jump
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| remote_jump_hostname=[string] | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
| jumpoint=[string] | The code name of the Jumpoint through which the endpoint is accessed. |
| group=[string] | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcut - Remote Jump
| tag=[string] | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments=[string] | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy=[string] | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
| session_policy=[string] | The code name of a session policy. You can specify a session policy to manage the permissions available on this Jump Item. |
| public_portal=[string] | The public portal through which this Jump Item should connect. |
Required parameters for import_jump_shortcut - Remote VNC
| remote_vnc_hostname=[string] | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
| jumpoint=[string] | The code name of the Jumpoint through which the endpoint is accessed. |
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| group=[string] | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcut - Remote VNC
| port=[integer] | A valid port number from 100 to 65535. Defaults to 5900. |
| tag=[string] | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments=[string] | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy=[string] | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
| public_portal=[string] | The public portal through which this Jump Item should connect. |
Required parameters for import_jump_shortcut - Local VNC
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| group=[string] | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
| local_vnc_hostname=[string] | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
Optional parameters for import_jump_shortcut - Local VNC
| tag=[string] | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments=[string] | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy=[string] | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
| public_portal=[string] | The public portal through which this Jump Item should connect. |
Required parameters for import_jump_shortcut - Remote Desktop Protocol
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| remote_rdp_hostname=[string] | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
| jumpoint=[string] | The code name of the Jumpoint through which the endpoint is accessed. |
| group=[string] | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcut - Remote Desktop Protocol
| rdp_username=[string] | The username to sign in as. |
| domain=[string] | The domain the endpoint is on. |
| display_size=[string] | The resolution at which to view the remote system. Can be primary (default - the size of your primary monitor), all (the size of all of your monitors combined), or XxY (where X and Y are a supported width and height combination - e.g., 640x480). |
| quality=[string] | The quality at which to view the remote system. Can be black_white (black and white for lowest bandwidth consumption), few_colors (8-bit color quality for fast performance), more_colors (16-bit color for medium color quality image and performance), full_colors (32-bit for true color reproduction), or video_opt (VP9 codec for more fluid video). This cannot be changed during the remote desktop protocol (RDP) session. |
| console=[boolean] | 1: Starts a console session. 0: Starts a new session (default). |
| ignore_untrusted=[boolean] | 1: Ignores certificate warnings. 0: Shows a warning if the server's certificate cannot be verified. |
| tag=[string] | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments=[string] | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy=[string] | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
| public_portal=[string] | The public portal through which this Jump Item should connect. |
| session_policy=[string] | The code name of a session policy. You can specify a session policy to manage the permissions available on this Jump Item. |
Required parameters for import_jump_shortcut - Local Remote Desktop Protocol
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| rdp_hostname=[string] | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
| group=[string] | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcuts - Local Remote Desktop Protocol
| rdp_username=[string] | The username to sign in as. |
| domain=[string] | The domain the endpoint is on. |
| display_size=[string] | The resolution at which to view the remote system. Can be primary (default - the size of your primary monitor), all (the size of all of your monitors combined), or XxY (where X and Y are a supported width and height combination - e.g., 640x480). |
| quality=[string] | The quality at which to view the remote system. Can be black_white (black and white for lowest bandwidth consumption), few_colors (8-bit color quality for fast performance), more_colors (16-bit color for medium color quality image and performance), full_colors (32-bit for true color reproduction), or video_opt (VP9 codec for more fluid video). This cannot be changed during the remote desktop protocol (RDP) session. |
| console=[boolean] | 1: Starts a console session. 0: Starts a new session (default). |
| ignore_untrusted=[boolean] | 1: Ignores certificate warnings. 0: Shows a warning if the server's certificate cannot be verified. |
| tag=[string] | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments=[string] | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy=[string] | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
| public_portal=[string] | The public portal through which this Jump Item should connect. |
| session_policy=[string] | The code name of a session policy. You can specify a session policy to manage the permissions available on this Jump Item. |
Required parameters for import_jump_shortcut - Shell Jump shortcut
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| shelljump_hostname=[string] | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
| jumpoint=[string] | The code name of the Jumpoint through which the endpoint is accessed. |
| protocol=[string] | Can be either ssh or telnet. |
| group=[string] | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcut - Shell Jump shortcut
| shelljump_username=[string] | The username to sign in as. |
| port=[integer] | A valid port number from 1 to 65535. Defaults to 22 if the protocol is ssh or 23 if the protocol is telnet. |
| terminal=[string] | Can be either xterm (default) or VT100. |
| keep_alive=[integer] | The number of seconds between each packet sent to keep an idle session from ending. Can be any number from 0 to 300. 0 disables keep-alive (default). |
| tag=[string] | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments=[string] | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy=[string] | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
| public_portal=[string] | The public portal through which this Jump Item should connect. |
| session_policy=[string] | The code name of a session policy. You can specify a session policy to manage the permissions available on this Jump Item. |
Required parameters for import_jump_shortcut - Intel vPro shortcut
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| vpro_hostname=[string] | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
| jumpoint=[string] | The code name of the Jumpoint through which the endpoint is accessed. |
| group=[string] | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcuts - Intel vPro shortcut
| tag=[string] | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments=[string] | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy=[string] | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
| public_portal=[string] | The public portal through which this Jump Item should connect. |
| session_policy=[string] | The code name of a session policy. You can specify a session policy to manage the permissions available on this Jump Item. |
XML response for import_jump_shortcut query
| <success> | Returns a message of Successfully imported Jump Item shortcut if the import succeeded. |
| <error> | Returns an error message if the import failed. |
Query examples: import_jump_shortcut
- Import a Local Jump shortcut to the endpoint with hostname "ABCDEF02", pinning it to team "remote_access"
https://support.example.com/api/command?action=import_jump_shortcut&name=Endpoint&local_jump_hostname=ABCDEF02&group=remote_access
- Import a Local Jump shortcut to the endpoint with hostname "ABCDEF02", pinning it to team "remote_access" and specifying its tag, comments, Jump Policy, and Session Policy
https://support.example.com/api/command?action=import_jump_shortcut&name=Endpoint&local_jump_hostname=ABCDEF02&group=remote_access&tag=Frequent%20Access&comments=Web%20server&jump_policy=Notify&session_policy=Servers
- Import a Remote Jump shortcut to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London", and pinning it to team "remote_access"
https://support.example.com/api/command?action=import_jump_shortcut&remote_jump_hostname=ABCDEF02&jumpoint=London&group=remote_access
- Import a Remote Desktop Protocol shortcut to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London", and pinning it to team "remote_access"
https://support.example.com/api/command?action=import_jump_shortcut&rdp_hostname=ABCDEF02&jumpoint=London&group=remote_access
- Import a Remote Desktop Protocol shortcut to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London", and pinning it to team "remote_access". Set the username, domain, display size, and quality. Make it a console session, and ignore untrusted certificates.
https://support.example.com/api/command?action=import_jump_shortcut&rdp_hostname=ABCDEF02&jumpoint=London&group=remote_access&rdp_username=admin&domain=example&display_size=1280x720&quality=more_colors&console=1&ignore_untrusted=1
- Import a Shell Jump shortcut to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London" on SSH, and pinning it to team "remote_access"
https://support.example.com/api/command?action=import_jump_shortcut&shelljump_hostname=ABCDEF02&jumpoint=London&protocol=ssh&group=remote_access
- Import a Shell Jump shortcut to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London" on SSH, and pinning it to team "remote_access". Set the username, port, and terminal type, and set the keep-alive time to two minutes.
https://support.example.com/api/command?action=import_jump_shortcut&shelljump_hostname=ABCDEF02&jumpoint=London&protocol=ssh&group=remote_access&shelljump_username=admin&port=25&terminal=vt100&keep_alive=120
- Import a Intel vPro shortcut to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London", and pinning it to team "remote_access"
https://support.example.com/api/command?action=import_jump_shortcut&vpro_hostname=ABCDEF02&jumpoint=London&group=remote_access
join_session
The join_session command adds a logged in representative to an existing support session.
Required parameters for join_session
| lsid=[string] | The ID of the session to which the representative will be added. |
| rep_id=[string] or rep_username=[string] | Unique ID or username assigned to the representative. To get a representative's ID, see get_logged_in_reps. |
XML response for join_session query
| <success> | Returns a message of Representative successfully added if successful. |
| <error> | Returns an error message if not successful. |
Query examples: join_session
- Add representative to session c69a8e10bea9428f816cfababe9815fe
https://support.example.com/api/command?action=join_session&lsid=c69a8e10bea9428f816cfababe9815fe&rep_id=151
leave_session
The leave_session operation removes a customer or representative from a session. It is the opposite of the join_session operation, except it also works on customers. This operation is necessary to remove the end user from the Remote Support session, when the end user disconnects from the chat bot at any time.
Parameters for leave_session
| lsid | This is the unique Logging Session ID (LSID) of the session in which the chat message will be sent. |
| rep_id (optional, see note) | The unique ID of the representative to remove from the session. |
| rep_username (optional, see note) | The username of the representative to remove from the session. |
| customer (optional, see note) | Must be have a value of1. If 1, the customer will be removed from the session. |
Note
You must provide one of the optional parameters listed (rep_id, rep_username, customer). If none of these parameters is provided, an error is returned.
Query examples: leave_session
https://support.example.com/api/command?action=leave_session
logout_rep
The logout_rep command logs out a specified user.
Required parameter for logout_rep
| rep_id=[string] | The unique ID representing the user you wish to logout. |
XML response for logout_rep query
| <success> | Returns a message of Successfully logged out if the logout was successful. |
| <error> | Returns an error message if the logout was not successful. |
Query examples: logout_rep
- User 375 logged out
https://support.example.com/api/command?action=logout_rep&rep_id=375
The logout_rep command logs out a specified user.
Required parameter for logout_rep
| rep_id=[string] | The unique ID representing the user you wish to logout. |
XML response for logout_rep query
| <success> | Returns a message of Successfully logged out if the logout was successful. |
| <error> | Returns an error message if the logout was not successful. |
Query examples: logout_rep
- User 375 logged out
https://support.example.com/api/command?action=logout_rep&rep_id=375
set_failover_role
The set_failover_role command sets the failover role of a B Series Appliance to either primary or backup.
Required parameter for set_failover_role
| role=[string] | The role to assign to this B Series Appliance. Can be either primary or backup. |
Optional parameters for set_failover_role
| data_sync_first=[boolean] | To perform a data sync with the peer B Series Appliance before failing over, set this to 1. All users on the existing primary B Series Appliance will be disconnected during the data sync, and no other operations will be available until the swap is complete. To fail over without a final data sync, set this to 0. |
| force=[boolean] | This option is only applicable when contacting the primary B Series Appliance and attempting to set its role to backup. If this is set to 1, then this B Series Appliance will become the backup even if the peer B Series Appliance cannot be contacted. |
XML response for set_failover_role query
| <success> | If a data sync is being performed first, returns a message of Successfully started data sync. Role change will occur upon successful completion. Otherwise, returns a message of Successfully changed role. |
| <error> | Returns an error message if the role was not set successfully. |
Query examples: set_failover_role
- Set failover role to primary
https://support.example.com/api/command?action=set_failover_role&role=primary
- Set failover role to backup
https://support.example.com/api/command?action=set_failover_role&role=backup
- Set failover role to primary and perform a data sync
https://support.example.com/api/command?action=set_failover_role&role=primary&data_sync_first=1
- Set failover role to backup and perform a data sync
https://support.example.com/api/command?action=set_failover_role&role=backup&data_sync_first=1
- Set failover role to backup even if the primary B Series Appliance cannot be contacted
https://support.example.com/api/command?action=set_failover_role&role=backup&force=1
- Set failover role to backup even if the primary B Series Appliance cannot be contacted, and perform a data sync
https://support.example.com/api/command?action=set_failover_role&role=backup&data_sync_first=1&force=1
set_rep_status
The set_rep_status command sets the status for representatives logged into the representative console.
Required parameter for set_rep_status
| rep_id=[integer] | The user ID of the representative whose status gets updated. |
| code_name=[string] | The code name of the status to set. |
XML response for set_rep_status query
| <success> | Present if the status was set successfully. |
| <error> | Returns an error message if the status was not set successfully. |
Query example: set_rep_status query
- Set the status of the representative with ID 5 to the status with the code name busy.
https://support.example.com/api/command?action=set_rep_status&rep_id=5&code_name=busy
set_session_attributes
The set_session_attributes command sets the external key and other custom attributes for an active support session.
Required parameter for set_session_attributes
| lsid=[string] | The ID of the session whose attributes you wish to set. The session must currently be active. |
Optional parameters for set_session_attributes
| 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 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. |
Note
If an attribute is not listed in the URL, it will keep its existing value. To clear an attribute, you must set the attribute to an empty string.
XML response for set_session_attributes query
| <success> | Returns a message of Session attributes were set if the attributes were set successfully. |
| <error> | Returns an error message if the attributes were not set successfully. |
Query examples: set_session_attributes
- Set external key for session c69a8e10bea9428f816cfababe9815fe
https://support.example.com/api/command?action=set_session_attributes&lsid=c69a8e10bea9428f816cfababe9815fe&session.custom.external_key=ABC123
- Set a custom value for session c69a8e10bea9428f816cfababe9815fe
https://support.example.com/api/command?action=set_session_attributes&lsid=c69a8e10bea9428f816cfababe9815fe&session.custom.custom_field1=Custom%20Value
transfer_session
The transfer_session command transfers an active session from one queue to another.
Required parameters for transfer_session
| lsid=[string] | The ID of the session you wish to transfer. |
| queue_id=[string] | The queue to which this session should be transferred. Can be one of rep:[id], team:[id], or rep_username:[string] where [id] is the numeric ID for the representative or team queue and [string] is the name of the representative to which you wish to transfer this session. To get a representative's ID or name, please see get_logged_in_reps. To get a team's ID, see <a href="#get_support_teams>get_support_teams. |
XML response for transfer_session query
| <success> | Returns a message of Successfully transferred if the transfer was successful. |
| <error> | Returns an error message if the transfer was not successful. |
Query examples: transfer_session
- Session c69a8e10bea9428f816cfababe9815fe to specific representative
https://support.example.com/api/command?action=transfer_session&lsid=c69a8e10bea9428f816cfababe9815fe&queue_id=rep:1
- Session c69a8e10bea9428f816cfababe9815fe to specific team
https://support.example.com/api/command?action=transfer_session&lsid=c69a8e10bea9428f816cfababe9815fe&queue_id=team:1
terminate_session
The terminate_session command terminates a support session that is in progress.
Required parameter for terminate_session
| lsid=[string] | The unique ID representing the session you wish to terminate. |
XML response for terminate_session query
| <success> | Returns a message of Successfully terminated if the termination was successful. |
| <error> | Returns an error message if the termination was not successful. |
Query examples: terminate_session
- Session da4b510978a541d49398e88c66e28475 terminated
https://support.example.com/api/command?action=terminate_session&lsid=da4b510978a541d49398e88c66e28475
Updated 5 days ago