ESP methods

Warning

It is vitally important to send userdata in every External Services Protocol (ESP) request as it contains several important parameters (such as the interaction ID) required by BGS to identify and start a bot. Both Interaction Routing Designer (IRD) and Composer contain an attribute of ESP block where sending userdata can be enabled.

StartBot

Parameter	Default value	Description
ChatBotID	(hardcoded)	Required. The ID of the BGS bot plugin (this ID is hardcoded inside the bot and returned by getBotId()). The combined length of ChatBotID and ChatBotName must be less than 49 characters.
_umsChannel	(empty string)	Required (see General notes). Value channel-chatbot must be provided.
ChatBotName	(empty string)	Optional. The name of the "external" bot (if the bot plugin implements a connector to other bot frameworks). The combined length of ChatBotID and ChatBotName must be less than 49 characters.
Nickname	(empty string)	Optional. Specifies how the bot will be presented in a chat session.
Visibility	ALL	Optional. Possible values are ALL, INT, VIP (see General notes).
StopBotOnAgentArrival	false	Optional. If true, BGS stops the bot when the first agent arrives in the chat session.
StopBotOnCustomerLeft	false	Optional. If true, BGS stops the bot when a customer leaves the chat session.
ChatBotHoldup	false	Optional. If true, BGS enforces waiting mode for the corresponded interaction. The workflow could wait until the bot finishes the execution. For more information about bot integration with the workflow, see How chat bots integrate with the workflow.
ChatBotCategory	(empty string)	Optional, but strongly recommended. Used to segregate historical reports. Max 50 characters allowed.
ChatBotFunction	(empty string)	Optional, but strongly recommended. Used to segregate historical reports in additional dimension to ChatBotCategory. Max 50 characters allowed.

Upon receiving the request, BGS checks whether this bot was already instantiated for this interaction and, if true, returns an error. The bot instance is identified by the pair ChatBotID and ChatBotName (where ChatBotName might be empty).

Otherwise, BGS:

1. Connects bot to the chat session with specified nickname and visibility level.
2. Invokes createChatBot methods of a bot plugin factory class in order to obtain the instance of the bot (which must implement the ChatBot interface).
3. Invokes onCommandStart of bot instance.

StopBot

Parameter	Default value	Description
ChatBotID	(hardcoded)	The same ID of the BGS bot provided in the ESP StartBot request.
_umsChannel	(empty string)	Required (see General notes). Value channel-chatbot must be provided.
ChatBotName	(empty string)	Required if this parameter was initially provided in the ESP StartBot requests. Otherwise, this parameter is optional.

Upon receiving the request, BGS checks whether this bot was instantiated for this interaction and, if false, returns an error. Otherwise, BGS:

• Disconnects the bot from the chat session.
• Invokes onCommandStop of bot instance.
• Disposes the chat bot instance.

Important

If there is no value specified for ChatBotId, BGS disconnect all bots (running in the BGS instance) for a given chat session.

CheckBot

Parameter	Default value	Description
ChatBotID	(harcoded)	The same ID of the BGS bot provided in the ESP Start request.
_umsChannel	(empty string)	Required (see General notes). Value channel-chatbot must be provided.
ChatBotName	(empty string)	Required if this parameter was initially provided in the ESP Start request. Otherwise, this parameter is optional.

Upon receiving the request, BGS checks whether this bot was instantiated for this interaction and, if false, returns an error. Otherwise, BGS returns an ESP success response.

UpdateBot

Parameter	Default value	Description
ChatBotID	(harcoded)	The same ID of the BGS bot provided in the ESP Start request.
_umsChannel	(empty string)	Required (see General notes). Value channel-chatbot must be provided.
ChatBotName	(empty string)	Required if this parameter was initially provided in the ESP Start request. Otherwise, this parameter is optional.
Arbitrary list of custom parameters that will be delivered to bot as a key-value collection (at least one parameter must be present).

This request allows the workflow to communicate data to the bot. The bot can communicate with the workflow by updating the userdata of the interaction (via updateUserdata in the ChatBotPlatform interface).
Upon receiving the request, BGS checks whether this bot was instantiated for this interaction and at least one custom parameter provided and, if false, returns an error. Otherwise, BGS invokes onCommandUpdate of bot instance.

General notes

• It is strongly recommended to always specify umsChannel=channel-chatbot in ESP requests. This is needed in particular, when a chat session is established via any DMS channels (such as Facebook, SMS, WeChat, and so on) or when BGS is running on a DMS instance with other channels configured.
• The Visibility parameter defines how a bot is visible to other participants in a chat session:
  • ALL (conference mode) – bot is visible to all participants.
  • INT (coaching mode) – bot is visible only to agents and supervisors.
  • VIP (monitoring mode) – bot is visible only to supervisors.

Important

A bot cannot send messages or notices to participants that do not see a bot. For example, if a bot is connected to a chat session with visibility set to INT, it cannot send messages to a customer like it can when visibility is set to ALL . When set to INT the bot can only send messages visible to both agents and supervisors.