Enhance CX with AI using the Genesys Bot GatewayJim CrespinoDirector, Developer Enablement

Bot Gateway Server Overview

• A specialized Digital Messaging Server (DMS) driver• Provides an integration platform for deployment of various chat

bots that participate in chat sessions conducted by Chat Server.• Equivalent of Workspace for automated agents• Maintains connectivity during a chat session between Chat Server

and the bot• sends user input to the bot• receives and forwards the bot response back to the user

Use Cases• Self-Service• Resolving customer issues without the need for a human agent to get

involved.

• Natural Language Processing• Rejecting comments that are in violation of profanity rules; determining

sentiment or analyzing the intent of a conversation to route a user to the

right bot or human agent.

• Agent Assist• Helping to guide a human agent through a conversation by delivering

relevant information in the context of the interaction.

• User Assist• Helping users with translations or PCI-compliant credit card transactions.

Architecture

How it works

• Deployed into a dedicated instances of DMS.

• Started and Stopped via ESP requests during routing.• Workflow sends ESP request StartBot to the BGS application.• Routing logic continues while bot interacts with customer• Bot is stopped by:

• Configured condition• ESP request to StopBot to the BGS application.

Bot Gateway Flow

Bot Gateway Server ESP API• Intended to be used from routing to send manage a bot.

• In order to send the command or request to BGS, the flow must use the External Service object and provide the following:

• Application Type: SocialMS• Application Name: The name of your DMS application where BGS is

deployed• Service Name: ChatBotPlatform• Method Name: StartBot, StopBot, CheckBot, or UpdateBot

StartBot MethodParameter Default

ValueDescription

ChatBotID (Required) (hardcode) The ID of the BGS bot plugin (returned by getBotId()).

ChatBotName (empty) The name of the "external" bot (if the bot plugin implements a connector to other bot frameworks).

Nickname (empty) Specifies how the bot will be presented in a chat session.

Visibility ALL Possible values:• ALL (conference mode)• INT (coaching mode)• VIP (monitoring mode).

StopBotOnAgentArrival

false If true, stops the bot when the first agent arrives in the chat session.

StopBotOnCustomerLeft

false If true, stops the bot when a customer leaves the chat session.

ChatBotHoldup false If true, BGS enforces waiting mode for the corresponded interaction. The workflow could wait until the bot finishes the execution.

StartBot Method (con’t)• 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:

• Connects bot to the chat session with specified nickname and visibility

level.

• Invokes createChatBot methods of a bot plugin factory class in order to

obtain the instance of the bot (which implements the ChatBot interface)

• Invokes onCommandStart of bot instance.

StopBot MethodParameter Default

Value

Description

ChatBotID (required) (hardcoded) The same ID of the BGS bot provided in the ESP Start request.

ChatBotName (empty) 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:

• 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 MethodParameter Default

ValueDescription

ChatBotID (required) (hardcoded) The same ID of the BGS bot provided in the ESP Start request.

ChatBotName (empty) 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 (501).

UpdateBot MethodParameter Default

ValueDescription

ChatBotID (required) (hardcoded

)

The same ID of the BGS bot provided in the

ESP Start request.

ChatBotName (empty) Required if this parameter was initially provided in the

ESP Start request. Otherwise, this parameter is optional.

Arbitrary list of parameters Will be delivered to bot as a key-value collection (at least

one parameter must be present).

This request allows the workflow to communicate some data to the bot. The bot can communicate

with the workflow by updating userdata of the interaction (via Bot Gateway Java API).

Upon receiving the request, BGS checks whether this bot was instantiated for this interaction and,

if false, returns an error. Otherwise, BGS invokes onCommandUpdate of bot instance.

Integrating Bots with a Workflow• Chat bots integrate with the workflow using the following modes:

• Waiting mode: The workflow waits while chat bot communicates with a customer. To use this mode, ChatBotHoldup must be set to true and a special view with a scheduling condition must be used.

• Parallel mode: The workflow immediately routes the interaction to an agent after the bot starts. The bot works in parallel with the agent.

• TIP: The Bot Gateway Server installation package (IP) provides a sample workflow that demonstrates both modes.

Conditions for Stopping a Bot BGS removes Bot

from Chat Session

When StopBot ESP request is received. with after

action keep-alive

When all participants (except bots, system, and external users) have left the chat session. with after

action keep-alive

When a bot instance explicitly requests (in Java API) to leave a chat session. with after

action keep-alive

When an agent joins a chat session (after the chat bot was already connected to the chat

session). This condition applies only if the parameter StopBotOnAgentArrival has a value

of true.

with after

action keep-alive

When a customer leaves a chat session (after the chat bot was already connected to the chat

session). This condition applies only if the parameter StopBotOnCustomerLeft has a value

of true.

with after

action keep-alive

When Chat Server removes the bot participant because the chat session is ending due to the

following conditions:

• Agent left the chat session with after-action close if no agents or force close

• Idle control monitoring.

• Interaction stopped when only customer was present in the chat session.

• Unrecoverable issue with UCS in HA (high-availability) mode.

• Chat Server shutdown in non-HA mode.

n/a

When BGS detects a disconnection from Chat Server, or a shut down of BGS has started. n/a

Deployment

Prerequistes• Chat Server version 8.5.109.06 or higher.

• DMS 9.0.000.16 or higher.• Deploy a dedicated instance for Bot Gateway

Refer to the Digital Messaging Server 9.0.0 Deployment Procedure for more information.

BGS Configuration: ‘channel-chatbot’ sectionOption Default Value Changes Take Effect

driver-classname com.genesyslab.chat.bots.cbpdriver.ChatbotDriver

After restart

hide-attached-data true Immediatelyholdup-reset-seconds 10 Immediately for new connectionsholdup-timeout-seconds

300 Immediately for new connections

inbound-route Valid value must be provided After restartmessage-log-print-size 0 Immediately

BGS Configuration: ‘channel-chatbot-monitor-chatbots’section

Option Value Changes Take Effect

<name of the bot plug-in

jar file>

The value provides the configuration for the

bot, which is provided to the bot with

method initialize of type KeyValueMap. This

value can:

• Contain {} (an empty configuration)

• Contain a JSON string (enclosed

between {} without line breaks)

• Contain the full path to the file with JSON

(line breaks allowed). The file name can be

absolute or relative (in case of relative

filename, the bots-repo directory is treated

as a root folder).

Restart required

IMPORTANT: Bot plug-in jar file must exist in the <DMS installation folder>/media-

channel-drivers/channel/chatbot/bots-repo folder

Testing Deployment• Activate the preinstalled EchoBot:• Deploy the provided sample workflow: ChatBotsGoBP.wie• Launch the Genesys Chat Widget• Userdata =

{ ChatBotID: "EchoBot" , ChatBotName: "EchoBot" , ChatBotHoldup: "false" , StopBotOnAgentArrival: "false" , StopBotOnCustomerLeft : "false" , Visibility : "ALL" , Nickname : "Demo Echo Bot" }

• EchoBot should join chat session and echo back message.• Stop EchoBot• Type: stop:keep_alive, stop:force_close, stop:close_if_no_agents, or stop

Developing a Bot

Prerequisites1. Install Java Development Kit 1.8.2. Install NetBeans 8.2 (https://netbeans.org/downloads/). You can

use the edition listed as Java SE (alternatively, you can use any other Java IDE.)

3. Install "Apache Maven 3". You can either:• Install it from https://maven.apache.org/download.cgi.• Install a Java IDE with Maven embedded.• Reuse embedded Maven in NetBeans (in Windows the mvn application is

located in the NetBeans installation folder under java\maven\bin).

Prepare Maven Environment1. Obtain Bot Gateway Server project template files

1. <DMS Installation folder>\media-channel-drivers\channel-chatbot\provision

2. Import the files into a local Maven repository by executing the following

commands from the location where the project template files are

stored:

• >mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file -

Dfile=ChatBotArchetype.jar -DpomFile=pom.xml

• >mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file -

Dfile=ChatBotApi.jar -Djavadoc=ChatBotApi-javadoc.jar

3. Update the archetype catalog in your local Maven repository with the

following command:

> mvn archetype:update-local-catalog

4. Restart your Java IDE

Update Maven pom.xml• Using NetBeans IDE, do the following:

• From the File menu select New Project.• Select Maven > Project from Archetype.

• Click Next.• Use the Search field to find the ChatBotArchetype archetype or select from

the Known Archetypes list.

• Click Next.• Modify the following:

• Project Name - Name of the project (same as artifact ID)

• Project Location - Where project will be placed

• Group Id - Maven groupId

• Version - Project version

• Package (Optional) - Package for Java classes (should be generated based on Group Id and Project Name)

• Click Finish.

Code Implementation Guidelines• Implement bot logic in the methods of the ChatBot interface.• Modify/Extend default implementation of the ChatBotFactory interface

• For example, you can change the getBotId() method if a different bot ID is needed.

• Use the ChatBotPlatform cbpInstance to:• Send messages or notices into the chat session• Leave the chat session• Update the userdata of interaction

• Verify proper ChatBotFactory class name in src\main\resources\META-INF\services file.• Refer to EchoBot implementation

• <DMS installation folder>\media-channel-drivers\channel-chatbot\samples

ChatBotFactory Classpublic class EchobotFactory implements ChatBotFactory {

private static final Logger LOG = LoggerFactory.getLogger(EchobotFactory.class);

public void initialize(KeyValueMap configuration) {// TODO to be implemented}

public void configurationUpdated(KeyValueMap configuration) {// TODO to be implemented}

public void shutdown() {// TODO to be implemented}

public ChatBot createChatBot(KeyValueMap espParameters, ChatInteractionInfo interactionInfo, BotCreationAttributes botCreationAttributes) {

return new Echobot();}

@Override public String getBotId() { return "EchoBot"; }}

ChatBot Classpublic class Echobot implements ChatBot {

private ChatBotPlatform cbpInstance;private Logger logger; // bot-session aware loggerprivate GenesysChatSession session;

public void setCbpInstance(ChatBotPlatform cbpInstance) {this.cbpInstance = cbpInstance;this.logger = cbpInstance.getLogger();

}

public void onCommandStart(GenesysChatSession session, int eventJoinedId, KeyValueMap espParameters) {

this.session = session;cbpInstance.sendMessage("Hello. I will echo back messages while You wait for the agent.");

}

public void onCommandStop(StopReason reason, ChatEventInfo eventInfo, KeyValueMap espParameters) { }

public void onSessionActivity(ChatEventInfo eventInfo) { }public void onCommandUpdate(KeyValueMap espParameters) { }

}

ChatBot Classpublic void onSessionActivity(ChatEventInfo eventInfo) {ChatUserInfo originator = session.getParticipant(eventInfo.getUserId());if (eventInfo.getEventType() == EventType.MESSAGE

&& originator.getUserType() != UserType.SYSTEM&& originator.getUserType() != UserType.EXTERNAL) {

if (eventInfo.getMessageText().matches("stop(:(force_close|keep_alive|close_if_no_agents))?")){

Action action = Action.CLOSE_IF_NO_AGENTS;String [] tokens = eventInfo.getMessageText().split(":");if (tokens.length > 1) { action = Action.valueOf(tokens[1].toUpperCase());}logger.info("Leaving chat session with after-action: " + action.name());cbpInstance.leaveSession(action);

} else {logger.info("Echoing back message: " + eventInfo.getMessageText());cbpInstance.sendMessage(eventInfo.getMessageText());

}}}

META-INF/services

Containschat.bots.echobot.EchobotFactory

In order for BGS to know which class in your Bot plug-in jar file contains the class that implements ChatBotFactory, you must include a file in the jar named:

META-INF/services/com.genesyslab.chat.bots.chatbotapi.ChatBotFactory

The file must contain a single line that provides the fully-qualified class name of your ChatBotFactory implementation.

Important!

Deploying a bot1. Copy the bot plugin JAR file to the subfolder media-channel-

drivers/channel-chatbot/bots-repo in the DMS installation folder.

2. Enable the bot plugin. Open the DMS Application object and go to the section channel-chatbot-monitor-bots (you must create the section if it is absent). Add an option where:

• The key contains the name of the bot plugin jar file (which is placed into the bots-repo folder). For example: MySampleBot.jar.

• The value provides the configuration for the bot, which is provided to the bot with method initialize of type KeyValueMap. This value can:

• Contain {} (an empty configuration)

• Contain a JSON string (enclosed between {} without line breaks)

• Contain the full path to the file with JSON (line breaks allowed). The file name can be absolute or relative (in case of relative filename, the bots-repo directory is treated as a root folder).

3. Observe the DMS logs to ensure the bot loads successfully.

4. Provide a workflow which starts, stops, and manages the bot.

Key Takeaways

Bot Gateway Server• A special purpose DMS channel driver

• Provides a Java-based plug-in framework for bots

• Bots can:

• Act as virtual agents

• Support live agents by provided guided responses

• Provide translation services between parties

• Handle specific conversation tasks such as credit card entry

What Now!• This Week• Visit us in the DevLounge area of

the Partner Pavilion

• After the Event• https://developer.genesys.com to

access our developer portals, Q&A forums, and resources

Thank YouVisit developer.genesys.com for more information