Outbound Events

Reference Guide - Variables and Macros

When integrating BeyondTrust with external programs, you can configure your B Series Appliance to send messages to an HTTP server or to an email address when specified events are triggered. This document lists the HTTP variables that can be sent by the outbound event service that resides on the B Series Appliance, describing what the messages mean as well as what triggered them. It also defines the macros that can be used in an email and lists the event emails that can include those macros.

HTTP Recipients

To configure HTTP recipients for outbound events, you should be familiar with the HTTP request concept and functionality. The variables sent by the B Series Appliance arrive as an HTTP POST method, and the server must respond with an HTTP 200 to indicate success. Failure to respond with an HTTP 200 will cause the B Series Appliance to re-queue the current event and retry it later. No other events will be sent until this event receives HTTP 200. This is to allow for a grace period should the event recipient need to be taken offline for a short duration; all the events the B Series Appliance missed while offline will arrive when it comes back online. The information can be accessed by calling the method used to retrieve POST data in your coding language.

Each message contains several standard variables, as defined below:

event	The name of the event that occurred. Events are further explained in the table below.
version	BeyondTrust's internal version number for this schema. This number will be updated whenever the schema changes.
timestamp	The Unix time stamp for the system time at which the event originated.

Each HTTP message contains the name of the event that triggered the message to be sent. Below is a comprehensive list of the possible events that would result in a post, accompanied by a brief description of each event. Note that each event includes variables in addition to the three standard variables defined above. The additional variables are also defined below.

Event ID and Name	Trigger	Additional Variables
support_conference_chat_message "Support Conference Chat Message"	This outbound event is sent every time a chat message is sent by a customer or representative in a session, including chat messages sent by the new send_chat_message Command API operation.	lsid: The logging Session ID of this event. This variable is present only when the message was sent to a session.
		external_key: Present only if an external key has been assigned to the session. This key can be assigned manually by the representative or programmatically and can be helpful in tracking issues in external programs. team_id: The logging Team ID of this event. This variable is present only when the message was sent to a support team.
		sender_type: The type of conference member who sent the chat message. Must be one of the following: customer (this value is only valid when the message was sent to a session), representative, or system.
		sender_name: The public display name of the conference member who sent the chat message. Only included when the sender_type is either customer or representative.
		sender_user_id: The unique ID of the representative who sent the chat message. Only included when the sender_type is representative.
		sender_username: The username of the representative who sent the chat message. Only included when the sender_type is representative.
		recipient_type: The type of conference member(s) who received the chat message. Must be one of the following: all, customer(this value is only valid when the message was sent to a session), representative, all_representatives.
		recipient_name: The public display name of the conference member who received the chat message. Only included when the recipient_type is customer or representative.
		recipient_user_id: The unique ID of the representative who received the chat message. Only included when the recipient_type is representative.
		api_account_id: The unique ID of the API account that sent the chat message using the send_chat_message Command API operation. Only included if the chat message was sent by the send_chat_message command. This field is included so that logging applications can detect impersonated chat messages.
		api_account_name: The name of the API account that sent the chat message using the send_chat_message Command API operation. Only included if the chat message was sent by the send_chat_message command. This field is included so that logging applications can detect impersonated chat messages.
		body: The original content of the chat message. The content may include one or more BBCodes for text formatting.
support_conference_chat_elevation_request "Support Conference Chat Elevation Request"	Tells the chat bot about the representative's requests to transition the end user from the 3rd party chat interface to the native Remote Support customer client.	lsid: The LSID of the session. external_key: The external key, if set. custom fields: Any custom fields that are set on the session.
support_conference_chat_elevation_succeeded "Support Conference Chat Elevation Succeeded"	Tells the chat bot the customer is no longer interacting with its session and can be closed.	lsid: The LSID of the session. external_key: The external key, if set. custom fields: Any custom fields that are set on the session.
support_conference_begin "Support Session Start"	A new support session has started.	lsid: The Logging Session ID of this event. Corresponds to the session ID as shown in the web reports or XML API reports. Must be treated as a string.
		external_key: Present only if an external key has been assigned to the session. This key can be assigned manually by the representative or programmatically, and can be helpful in tracking issues in external programs.
support_conference_end "Support Session End"	A support session has ended.	lsid: The Logging Session ID of this event. Corresponds to the session ID as shown in the web reports or XML API reports. Must be treated as a string.
		external_key: Present only if an external key has been assigned to the session. This key can be assigned manually by the representative or programmatically, and can be helpful in tracking issues in external programs.
support_conference_owner_changed "Support Session Ownership Changes"	The session has been transferred to the designated representative or team. Occurs when the session is first started, when a representative transfers a session to another representative or team, or when the primary representative leaves an active session.	lsid: The Logging Session ID of this event. Corresponds to the session ID as shown in the web reports or XML API reports. Must be treated as a string.
		external_key: Present only if an external key has been assigned to the session. This key can be assigned manually by the representative or programmatically, and can be helpful in tracking issues in external programs.
		conference_id: The unique ID assigned to the representative or team (for example, rep:12, team:5).
		conference_name: The name of the representative or team (for example, John Smith, Troubleshooting).
support_conference_member_added "Someone Joins a Support Session"	A new individual, either a customer or representative, has joined the session.	lsid: The Logging Session ID of this event. Corresponds to the session ID as shown in the web reports or XML API reports. Must be treated as a string.
		external_key: Present only if an external key has been assigned to the session. This key can be assigned manually by the representative or programmatically, and can be helpful in tracking issues in external programs.
		type: The type of individual who was added. Can be either customer or representative.
		name: The display name of the individual.
		user_id: Present only if the individual is a representative. The unique ID assigned to that representative.
		username: Present only if the individual is a representative. The username assigned to that representative.
support_conference_member_departed "Someone Leaves a Support Session"	A customer or representative has left the session.	lsid: The Logging Session ID of this event. Corresponds to the session ID as shown in the web reports or XML API reports. Must be treated as a string.
		external_key: Present only if an external key has been assigned to the session. This key can be assigned manually by the representative or programmatically, and can be helpful in tracking issues in external programs.
		type: The type of individual who was added. Can be either customer or representative.
		name: The display name of the individual.
		user_id: Present only if the individual is a representative. The unique ID assigned to that representative.
		username: Present only if the individual is a representative. The username assigned to that representative.
support_conference_customer_exit_survey_completed "Customer Exit Survey is Completed"	The customer has submitted the customer exit survey.	lsid: The Logging Session ID of this event. Corresponds to the session ID as shown in the web reports or XML API reports. Must be treated as a string.
		external_key: Present only if an external key has been assigned to the session. This key can be assigned manually by the representative or programmatically, and can be helpful in tracking issues in external programs.
support_conference_rep_exit_survey_completed "Representative Survey is Completed"	The primary representative has submitted the representative survey.	lsid: The Logging Session ID of this event. Corresponds to the session ID as shown in the web reports or XML API reports. Must be treated as a string.
		external_key: Present only if an external key has been assigned to the session. This key can be assigned manually by the representative or programmatically, and can be helpful in tracking issues in external programs.

Email Recipients

To configure email recipients for outbound events, you must first verify that your B Series Appliance is configured to work with your SMTP relay server. The SMTP settings are configured from /login > Management > Email Configuration.

Within the Email Recipients section of the Outbound Events page, the Current Status displays a brief status message from the SMTP relay server. As long as the B Series Appliance is able to send messages to the relay server, the status will show OK. Otherwise, review your SMTP relay server settings. Also, if an event continues to retry and fail, set how long it should continue to retry before being dropped.

Each email message triggered by an event is completely free-form and can be modified to whatever text format the recipient requires. Below is a list of the available macros that can be used in emailed outbound events, along with which macros can be used with which events.

Macro	Purpose and Availability	Event
%SESSION.CUSTOM.EXTERNAL_KEY%	Present only if an external key has been assigned to the session. This key can be assigned manually by the representative or programmatically, and can be helpful in tracking issues in external programs (Subject and Body).	Support Session End
		Customer Exit Survey is Completed
		Representative Survey is Completed
%LSID%	The logging Session ID of this event. Corresponds to the session ID as shown in the web reports or XML API reports (Subject and Body).	Support Session End
		Customer Exit Survey is Completed
		Representative Survey is Completed
%LSEQ%	The sequential logging number used to represent this support session (Subject and Body).	Support Session End
		Customer Exit Survey is Completed
		Representative Survey is Completed
%CUSTOMER_NAME%	The name of the customer (Subject and Body).	Support Session End
%CUSTOMER_COMPUTER-NAME%	The name of the customer's computer (Subject and Body).	Support Session End
%PRIMARY_REP_PRIVATE_DISPLAY_NAME%	The primary representative's private display name (Subject and Body).	Support Session End
%PRIMARY_REP_PUBLIC_DISPLAY_NAME%	The primary representative's public display name (Subject and Body).	Support Session End
%PRIMARY_REP_USER_NAME%	The primary representative's user name (Subject and Body).	Support Session End
%START_TIME%	The time at which the session started (Subject and Body).	Support Session End
%END_TIME%	The time at which the session ended (Subject and Body).	Support Session End
%SESSION_SUMMARY%	A summary of session details, including the representative's private display name and ID, the customer's name and IP addresses, the session start time, end time, and duration, and the number of files transferred, renamed, or deleted (Body).	Support Session End
%SESSION_NOTES%	Any session notes submitted during the support session (Body).	Support Session End
%SESSION_CHAT%	The entire chat transcript of the support session (Body).	Support Session End
%SYSTEM_INFORMATION%	The General Information section of the retrieved system information. System information is returned only when pulled automatically at the beginning of the session and not when specifically requested by the representative. This is to prevent overload with the large amount of dynamic data that can be retrieved from the remote system (Body).	Support Session End
%SCREEN_SHARING_RECORDING%	The URL of the screen sharing recordings (Body).	Support Session End
%COMMAND_SHELL_RECORDING%	The URLs to all command shell recordings (Body).	Support Session End
%CUSTOMER_EXIT_SURVEY%	The exit survey questions presented to the customer and their responses (Body).	Customer Exit Survey is Completed
%REPRESENTATIVE_EXIT_SURVEY%	The exit survey questions presented to the representative and their responses (Body).	Representative Survey is Completed