Give us feedback
multilingual-chatbot
Mobile icon

Multilingual Chatbot

Stable version 1.0.0 (Compatible with OutSystems 11)
Published on 30 Mar by 
0.0
 (0 ratings)
multilingual-chatbot

Multilingual Chatbot

Documentation
1.0.0

Learn how to use the Multilingual Chatbot accelerator app that simultaneously uses AWS Lex as a chatbot and AWS Translate services are used inside it.

Setting up the accelerator

To correctly set up the Multilingual Chatbot accelerator you’ll need to:

  1. Create a bot in Amazon Lex console.

  2. Create an app in Service Studio to use the accelerator

  3. Configure the Site Properties in Service Center to finish the configuration.

Step 1 - Create a bot in Amazon Lex Console

To create a bot through the Amazon Lex console

  1. Make sure to use the V2 of the Amazon Lex service and make sure to pick the correct region.

  2. Create the bot based on the BookTrip sample that Amazon provides.

  3. Configure the BotId, BotAliasId, and BotLocale. Then, publish it.

  4. On the Amazon Identity and Access Management (IAM) console, create a user with programmatic access and grant it the existing policy AmazonLexRunBotsOnly, in order to retrieve the AccessKey and the SecretKey for that user.

Step 2 - Create an application in Service Studio

Now that you have created the bot in the Amazon Lex Control, go to OutSystems' Service Studio and do the following:

  1. Create a new application from scratch and use the template_intentprocessor (included inside the multilingual chatbot app). 

  2. To minimize configurations, call the new module AWSIntentProcessor (This is the broker developed by us to process all the outcomes):

    • This broker receives the name of the intent, a dictionary list (list of key-value pairs), and returns if the outcome was successful or not. With this, the IntentName is parsed and it proceeds to invoke the corresponding server action to process the request.
      This is a very simple example of how to process the intent to parse the input (DictionaryList) and create a database record for it. Currently, the platform doesn’t support lists of “key: value” pairs in JSON responses when the key is variable – like a dynamic list -, as AWS returns to our integration, it’s needed to use a parser to convert the “key: value” to a list of “Key”: <actual key name>, “Value”: <key value>. 
      Then it’s needed to filter out the slots based on the expected keys and then map to the structure – or just do what is needed to do with them.

  3. Whenever it is necessary to modify the business logic – or add new intents -, just modify the IntentProcessor REST endpoint.

Step 3 - Configure all the Site Properties in Service Center

  1. On ServiceCenter, go to the Multilingual Chatbot accelerator app that you have created in step 2, and configure the Amazon_AccessKey, Amazon_Region, Amazon_SecretKey, BotAliasId, BotId, BotLocale and IntentProcessorModuleName site properties with the values created in the previous steps. 

You are now ready to use the accelerator app.

How to use the accelerator

The Multilingual Chatbot accelerator provides a web block named Chatbot (in the PublicFlow), that consists of a ready-to-use chatbot, and forms the foundation of the entire application:


 Parameters:

BotDisplayName: the name that will appear on the messages sent by the bot itself.

ConversationGUID: the GUID of the conversation.

CurrentMessageSenderTypeId: the Id of the type of the message sender (Agent/Bot/User).

MessagesCountLimit (not mandatory): The limit of messages per conversation (default value of 100)

SenderName: The name of the sender of each message.

In a real scenario, the logic to limit the number of messages per conversation, should be entirely removed from the code.


Events:

DispatchConversationState: this event is fired every time the state of the conversation changes.


Main Flows

The Multilingual Chatbot accelerator app has two main UI Flows: 

The UserFlow

This flow is composed of the Home screen which functions as a landing page and where it is possible to choose between the user’s view or the agent's view, and the LexChatbot screen which incorporates the Chatbot block and represents the user’s view. The LexChatBot screen is the one you should look into with more attention as it implements the chat screen with the bot.

The conversation with the bot is established in the language to which the bot was configured to respond to( in our sample we only have an English speaking bot, if you want to configure a multi-lingual Lex bot check this page from the AWS blog)

If for some reason, the bot is not able to respond to all the requests, the user has the possibility to call the intervention of a human agent by clicking on the following button:

The AgentFlow

This is an example of what could be the functionality available for a call-center agent. In a real scenario, you should add authentication and manage the users that access this resource.



Here, it’s possible to:

  • Setup the agent itself, in particular its name and spoken language. (this screen should not be re-used. It's here only for demo purposes.)

  • Manage the conversations

    • Pickup conversations waiting for an agent. 

    • Resume any ongoing conversation.

    • View the log of conversations that were already archived


  • Whenever an agent picks up a conversation, and through the use of the AWS Translate service, that conversation is totally translated and presented to the agent into his own language (if his and the user's differ).

  • When an agent picks a conversation, that same conversation can’t not be picked by another agent. (this is an example of a business rule that we implemented. You can change to fit your needs)


Conversation State Diagram

Each conversation can assume four different states:

Data Model


  • Conversation: Entity that stores the list of conversations.

  • ConversationMessage: Entity that stores the list of messages in a conversation.

  • ConversationState: Static entity with the possible states of a conversation.

  • Language: Static entity with the languages supported by Amazon Translate.

  • MessageSenderType: Static entity with the type of the message sender.


IntentProcessor

In order to process the outcome, we will use a broker. This broker is developed by us.


The Multilingual Chatbot accelerator comes with a Service Template as a starting point from where you can build this broker.


The MultilingualChatbot module is pre-wired to an Intent Brooker called AWSIntentProcessor, so if you change the name of the module, you need to reconfigure the IntentProcessorModuleName on MultilingualChatBot's site properties.


NOTE: If you have previously created an Intent Processor module in the scope of Alexa or Self Service Chatbot, you can re-use it by pointing the MultilingualChatbot to that pre-existing Intent Processor.

Our broker receives the name of the intent, a dictionary list (list of key-value pairs), and returns if the outcome was successful or not. In other words, we just parse the IntentName and proceed to invoke the corresponding server action to process the request. This is a very simple example of how to process the intent to parse the input (DictionaryList) and create a database record for it.

Currently, the platform doesn’t support lists of “key : value” pairs in JSON responses when the key is variable – like a dynamic list -, as AWS returns to our integration, so we need to use a parser to convert the “key : value” to a list of “Key” : <actual key name>, “Value” : <key value>. Then we need to filter out the slots based on our expected keys and then map to the structure – or just do what you need to do with them.


Whenever you want to modify your business logic – or add new intents -, just modify the IntentProcessor REST endpoint. 

IMPORTANT NOTE: don’t forget to configure your IntentProcessor endpoint!