Lex Integration

Overview

Kommunicate provides a codeless integration with Amazon Lex. You can easily integrate a bot form bot section in the Kommunicate dashboard. In this section, learn how to:

Integrate with Lex

Kommunicate requires the following information to interact with your bot. You can obtain this information from the AWS console.

A. Access Key ID & Secret access key: An access key ID and secret access key are required to sign requests you make using the AWS SDKs. To get your access key sign into your AWS console as a Root or IAM user.

  1. Open the Identity and Access Management (IAM) panel in the same AWS account where the Lex bot is present.

  2. Go to “Access management -> Users”. Create a user by clicking the “Add Users” button. Add a user name eg: “Lex-bot”.

LexInt1

  1. Set permissions: Choose "Attach Policies Directly"

  2. Select the following two permissions: AmazonLexReadOnly & AmazonLexRunBotsOnly

LexInt2

  1. Keep the "Tags" empty and proceed to Next.

  2. On the next page confirm the attached permissions to the user and click on “Create User”.

  3. Now that your user is created, select the user, and on the next page click on Security Credentials.

LexInt4

  1. Scroll down and click on Create Access Key.

LexInt4

  1. Select Third-Party Service and proceed next to generate the access keys.

LexInt4

A. Bot name in Lex platform: Lex requires a name for your bot when you create it. Once you create the bot, you can also get it from the bot list in Lex home page.

B. Bot Alias: You create a bot alias when you publish the bot. It helps you to work with multiple versions of your bot. Update the bot alias in Kommunicate if you want Kommunicate to connect with a specific version of the bot.

C. Region: AWS region where Lex service is running. You can find your region in the top-right corner following the user name in the AWS console.

Once you have the above information follow the below steps to integrate the bot with Kommunicate:

  1. Log in to Kommunicate and go to bot section.
  2. Click the Integrate Bot in the Amazon Lex card.
  3. Fill in the required detail and click next.
  4. Give your bot a name. This name will be visible to your users who interact with the bot.
  5. Enable/Disable the autoHandoff setting if you want your bot to assign the conversation to a human agent in your team when the conversation is hung up by the bot.
  6. Click on Let this bot handle all new conversations. All new Conversations started after the integration will be assigned to this bot and your bot will start answering them.

NOTE: Make sure to choose the same language for the bot in both Lex and Kommunicate.

LexInt4

LexInt4

Welcome message from bot

When a conversation is created and routed through the bot, Kommunicate notify the Lex platform so that the bot can send the welcome message to your users. Below is the message Kommunicate sends to the Lex - kmConversationStarted

You need to create an intent and add above string to the sample utterance section. Set the welcome message in the response of this intent.

This message is different from the Welcome Message you set in Kommunicate dashboard. If Welcome Message for bot and humans (configured from the dashboard) both are enabled, both welcome message will be sent to the users. We recommend disabling the Welcome Message from the dashboard in this case.

Lex-Welcome-Message

Bot to human handoff

Bot to human handoff allows you to seamlessly switch from a bot to a human agent when the bot is unable to answer the query on its own. There are two ways to achieve it.

When bot is not able to answer

Lex console has a Error handling section to deal with those scenarios where your bot is not able to answer. You can set a message in clarification prompt to tell the user that his query did not match any intent. After a certain number of retries if no intent is detected in user's query the bot will display a message set in the 'Hang-Up Phrase' section. Kommunicate will automatically detect this message and handoff the conversation to the assigned human agent according to the Conversation Rules you've set up on your dashboard.

The Maximum number of retries before the bot hands-off the conversation and the Hang-up phrase can be configured from the AWS Lex dashboard in the Error-Handling section in your bot's Editor tab as shown in the picture below.

Lex-Hand-Off

Amazon Lex V2 does not support clarification prompts and hang up phrases (abort statements). Amazon Lex V2 bots contain a default fallback intent that is invoked if no intents are matched. To send a clarification prompt with retries, configure a Lambda function and enable the dialog code hook in the fallback intent. The Lambda function can output a clarification prompt as a response and the retry value in a session attribute. If the retry value exceeds the maximum number of retries, you can output a hang up phrase and close the conversation.

When a specific intent is detected

You can configure your bot to handover the conversation to human when a specific intent is detected. You have to set the below JSON as the custom markup in the response section.

{
  "platform": "kommunicate",
  "message": "our agents will get back to you",
  "metadata": {
    "KM_ASSIGN_TO": ""
  }
}

if you want to assign the conversation to a specific human agent then pass the agent's login id in KM_ASSIGN_TO parameter.

Using Rich messages

There are two ways you can use rich messages with your Lex bot.

Note: You can only use rich messages that are of less than 1000 characters.

Enable cards in response

Lex has the builtin support for the card messages. In the response section of the intent enable the response card setting and enter the required detail. Once intent is saved and the published Kommunicate will render that card in chat widget.

Add Kommunicate rich messages as custom markup

You can use the all type of rich messages provided by Kommunicate with Lex. You can set the respective JSON as the custom html in response section of the intent. Once this is done you need to save and publish the bot to see the rich messages in chat widget. rich messages using custom markup

Make the bot multilingual

Kommunicate allows you to integrate your multilingual bot so that your bot can reply in the user's language. You need to pass the user's language tag to Kommunicate.

Language tags follow the HTTP/1.1 specification, section 3.10. Kommunicate will send this information with every message to the integrated bot platform. You can use the below method to update the user's language for Lex V2 only.


Kommunicate.updateUserLanguage("en-US");

Call the above method when the Kommunicate SDK is initialized. Refer to "onInit" callback function in installation script.

Send attachments and location to bot

To receive the file attachment and location details, you need to create a lambda function which can process the attachments. Create a new intent with kommunicateMediaEvent expression in Sample utterances section and select the AWS Lambda function from the fulfillment.

When a user attaches a file or shares location, Kommunicate sends this information in Request Attribute parameter to your lambda function. You can do the further processing and return confirmation to the user.

This is sample JSON for file attachment:

{
    "attachments": [{
        "payload": {
            "size": "Size in bytes",
            "name": "Name of the file",
            "url": "URL of the file"
        },
        "type": "image/png" // media type (in form of type/subtype) . Use the regex 'type/*' to get the generic type
    }]
}

Sample JSON for the location message

{
    "attachments": [{
        "payload": {
            "lat": "Latitude",
            "lon": "Longitude"
        },
        "type": "location"
    }]
}
← Dialogflow IntegrationKompose Bot Builder →