Amazon Lex V2 quick start guide

Amazon and Genesys developed a partnership to help organizations deliver advanced capabilities to enhance customer experiences, blending AI and Amazon Lex V2 voice interaction technologies with Genesys Cloud contact center automation.

Click the image to enlarge.

Quick start steps

This quick start article helps guide you through implementing the Amazon Lex V2 integration. Here, you learn how to perform the following steps:

  1. Create an Amazon Lex V2 bot.
  2. Grant Genesys permissions to call the Amazon Lex V2 bot.
  3. Obtain the Amazon Lex V2 integration from Genesys AppFoundry.
  4. Configure and activate the Lex V2 integration in Genesys Cloud.
  5. Create a Genesys Cloud Architect flow and configure it with an Amazon Lex V2 bot.
  6. Use Genesys Cloud to call the Architect inbound call flow.

Step 1: Create an Amazon Lex V2 bot

The process of creating Lex V2 bots is documented by Amazon. Since the process could change, refer to Amazon documentation when creating bots. This example explains how to create a simple bot. To create this bot, use the Bots interface in Amazon Web Services (AWS).  

Prerequisites

Create the initial bot and add a name, language, voice, and basic information

  1. Sign in to the AWS Management Console and open the Amazon Lex V2 console.
  2. Click Create bot.
  3. Under Creation method, select Create.
  4. Under Bot configuration, give the bot a name and an optional description. For example, “BankBot.”
  5. Under IAM permissions, choose a role that defines permissions for the bot. Here, select an existing role.
  6. Under Children’s Online Privacy Protection Act (COPPA), choose the appropriate response. In this example, select No.
  7. Under Idle session timeout, choose the duration that Amazon Lex V2 keeps a session with a user open. Amazon Lex V2 maintains session variables during the session so that your bot can resume a conversation with the same variables. In our example, leave the default setting.
  8. Leave all other settings unchanged.
  9. To create the bot and continue to adding a language, click Next. The Add language to a bot page opens.
  10. Add language and a voice for the bot to use:
    1. Under Select Language, choose the appropriate language for the bot. Here, leave the default English language. 
    2. Under Voice interaction, select the text-to-speech voice that your bot uses to interact with users. Here, select Kendra.
    3. Under Intent classification confidence score threshold, set the value that Amazon Lex uses to determine whether an intent is the correct intent. In our example, leave the default value of 4.0.
    4. Click Done. The Intent editor opens.

Add intents and slots and then build the bot

In our example, create two intents: a welcome message intent and an account balance intent with a simple utterance and a single slot. Then, build the bot.

Note: Make sure that you add the welcome intent. This intent attempts to solicit initial audio from the bot and, if excluded, results in a resources error.

  1. Add the welcome message intent. This intent does not have slots, but has a closing message. This message is the first thing that the caller hears.
    1. Click Add intent and then click Add empty intent
    2. Under Intent name, type “WelcomeMessage” and then click Add.
    3. Under Closing responses, in the Message box type “Thank you for calling. I can help with routing banking tasks. How can I assist you?”
    4. Leave the remaining settings unchanged.
    5. Click Save intent.
  2. Add the account balance intent.
    1. Click Add intent and then click Add empty intent
    2. Under Intent name, type “CurrentBalance” and click Add. The Intent editor opens.
    3. Under Sample utterances, type “Account balance.”
    4. In the Sample utterances text box, type, “What is my account balance?” and then click Add utterance
    5. Under Slots, click Add slot.
    6. In the Name box, type AccountNumber.
    7. Under Slot type, select AMAZON.number.
    8. Under Prompts, type, “Please enter your account number.”
    9. Click Add.
    10. Click Save intent.
  3. Click Build.
  4. Create a version and an alias.

Step 2: Grant Genesys the permissions to call the Amazon Lex V2 bot

To access Amazon Lex V2 bots, Genesys Cloud must have permission to use resources in Amazon Web Services (AWS). This procedure explains how to set up an IAM role in AWS. This role is assigned to Amazon Lex V2 later, when you configure and activate the app in Genesys Cloud.

Note: The bot contains a default version of DRAFT and a default alias of TestBotAlias. Use this alias for limited testing. If you use it in realtime, you may exceed limits and encounter failed calls.

Prerequisites

To configure an IAM role:

  1. Log in to AWS.
  2. Navigate to the AWS Services page and select IAM.
  3. Under Dashboard, select Roles.
  4. On the Roles page, click Create role.
  5. Select Another AWS Account as the type of trusted entity.
  6. In the Account ID box, enter 765628985471 in the Account ID box. This number is Genesys Cloud’s production account ID.
  7. To enhance security, Genesys recommends that you check the Require External ID box and enter your organization’s ID.
  8. Click Next: Permissions.
  9. Next, assign permission policies to the role. In the search box, type Lex V2. Then select the AmazonLexReadOnly and AmazonLexRunBotsOnly policies check boxes.
  10. Click Next: Tags.
  11. (Optional) Add metadata to the role by attaching tags as key-value pairs. 
  12. Click Next: Review.
  13. In the Role Name box, type a name. For example, DemoLexRole.
  14. In the Role description box, enter descriptive text about the role.
  15. Verify that the account number for Trusted entities matches the Genesys Cloud production account ID you entered in step 6.
  16. Click Create Role.
  17. In the listing page, click the name of the role. This link is the name you entered in the Role Name box in step 12. Summary details about the role appear.
  18. Note the Role ARN. You need this credential later. An Amazon Resource Name (ARN) is a unique identifier that unambiguously identifies a resource.
  19. Click the Copy icon (to the right of Role ARN), which copies your ARN to the clipboard. 

Create a Lex V2 policy in JSON format in the AWS console and then assign it to your IAM role. This policy ensures that Genesys Cloud Architect can interact with an Amazon Lex V2 bot.

  1. Sign in to the AWS Management Console and open the IAM console.
  2. In the navigation pane on the on the left side, click Policies.
  3. Click Create policy.
  4. Click the JSON tab.
  5. Type or paste the following JSON content: 
    {
         Version": "2012-10-17",
         "Statement": [
              {
                   "Sid": "VisualEditor0",
                   "Effect": "Allow",
                   "Action": [
                        "lex:List*",
                        "lex:Describe*",
                        "lex:StartConversation",
                    ],
                    "Resource": "*"
              }
         ]
    }
  6. Resolve any security warnings, errors, or general warnings that the policy validation generates, and then click Review policy.
    Note: You can switch between the Visual editor and JSON tabs anytime. However, if you make changes or choose Next: Tags in the Visual editor tab, IAM might restructure your policy to optimize it for the visual editor.
      
  7. Click Next: Tags.
  8. (Optional) Add metadata to the policy by attaching tags as key-value pairs. 
  9. On the Review policy page, type a Name and a Description (optional) for the policy. Review the policy Summary to see the permissions that your policy grants.
  10. Click Create policy.
  11. After you create a policy, attach it to the IAM role that you created above.

Example:

Step 3: Obtain the Amazon Lex V2 integration from Genesys AppFoundry

This section describes how to obtain and install the Amazon Lex V2 integration in Genesys Cloud.

Prerequisites

  • Contact Genesys Cloud Sales and request to update your subscription.

To install Amazon Lex V2 in your org:

  1. Log in to Genesys Cloud for the org in which to add Amazon Lex V2.
  2. Click Admin.
  3. Under Integrations, click Integrations.
  4. Click Integrations.
  5. In the Search box, type Amazon Lex V2. The card for Amazon Lex V2 appears.
  6. Click the Amazon Lex V2 card. Information about the app appears.
  7. Click Install.

Amazon Lex V2 is now available to configure and activate from Genesys Cloud’s Admin > Integrations page. 

    Step 4: Configure and activate the Lex V2 integration in Genesys Cloud

    This section describes how to enable and set up the Amazon Lex V2 integration in Genesys Cloud.

    To access the Call Lex V2 Bot action in Architect, you must first add and configure the Amazon Lex V2 integration and then grant permission to access AWS resources in your org. 

    1. In Genesys Cloud, click Admin.
    2. Under Integrations, click Integrations.
    3. Click Add Integration.
    4. Locate the Amazon Lex V2 integration.
    5. In the Amazon V2 Lex tile, click Install. Genesys Cloud installs the integration.
    6. Click Integrations.
    7. Next to Amazon Lex V2, click More  and select Edit Integration.
    8. Click the Configuration tab and then click the Credentials tab.
    9. Click Configure
    10. In the Role ARN box, press Ctrl+V to paste the ARN you stored on the Clipboard into the Role ARN box. If you use a Mac, press Command+V to paste. 
    11. Click OK and then click Save.
    12. Select the Details tab.
    13. To activate the integration, click Inactive. The Change Status dialog appears and asks you to confirm that you want to activate Amazon Lex.
    14. Click Yes. The status changes to Active.

    Step 5: Create a Genesys Cloud Architect flow and configure it with an Amazon Lex V2 bot

    These steps ensure consistency between the bot and the flow.

    Note: By default, you can only select Default or Genesys TTS. Before you can use Amazon Polly, you must install and configure the integration. For more information, see Getting Started with Amazon Polly in the Amazon Polly Developer Guide and Install the Amazon Polly integration in the Genesys Cloud Resource Center.

    Prerequisite

    • An Amazon Lex V2 bot configured in the AWS console. 

    To create an Architect flow, perform these steps:

    1. In Genesys Cloud, click Admin.
    2. Under Architect, click Architect. The Architect home page appears.
    3. From the Architect home page, click or hover over the Flows menu and choose Inbound Call Flow.
    4. Click Add . The Create Flow dialog box opens.
    5. In the Name field, enter a unique name for the flow. Here, enter “BankingBot.”
    6. (Optional) In the Description field, include a short sentence or phrase to describe this flow.
    7. Click the Default Language list and select the flow’s default supported language. In this example, leave the default English language.
    8. Click the Divisions list and select the division in which to place the flow. In this example, use the default Home division.
    9. Click Create Flow. The flow configuration page opens.

    These steps ensure consistency between the bot and the flow.

    1. Under Settings, click Supported Languages.
    2. In the Supported Languages panel, under Text To Speech, choose Amazon Polly.
    3. Under Voice, select Kendra.

    Example:

    Create a new task and call the Lex V2 bot.

    1. Under Reusable Tasks, click Add reusable task here, then click Toolbox and select Task.
    2. Above the task editor, rename the task “Self-service” and click Done.
    3. Click More and from the menu that appears, click Set this as the starting task.
    4. From the Toolbox, expand the Bot category and drag a Call Lex V2 bot action into the task editor.
    5. In the Call Lex V2 Bot panel, configure the action:
      1. Under Bot Name, select BankBot.
      2.  Under Bot Alias, select TestBotAlias.
      3. Under Initial Intent Name, specify the welcome message intent that you previously created, “WelcomeMessage.”

    Under Intents, notice that Architect includes paths for each possible matching intent. 

    1. To capture the account number into an Architect variable, under CurrentBalance type “Task.AccountBalance.”
    2. Add an audio sequence to the CurrentBalance path.
    3. From the Toolbox, expand the Audio category and drag a Play Audio action into the task editor, below the CurrentBalance path.
    4. In the Play Audio panel, next to Audio click Audio Sequence . The Audio Sequence dialog box opens.
    5. In the Text To Speech box, type “I see that your account number is.”
    6. Click Add Data, and in the Data box type Task.AccountNumber.
    7. Click Select options and choose Speak each character.
    8. Click Close.
    9. Continue to add outcome paths for each intent. For example:
      • Add another Play Audio action below the CurrentBalance path that reads the account balance back to the customer.
      • Add a Transfer to ACD action and transfer the call to a support team in case the flow takes the Failure path.
    10. Add a Disconnect action to the end of the task.
    11. Click Publish.

    Example:

      Step 6: Use Genesys Cloud to call the inbound call flow

      Now, call the BankingBot flow in Genesys Cloud and test the bot.

      To configure the call route entry, perform the following steps:

      1. In Genesys Cloud, to open the Calls panel click Calls .
      2. In the Enter names and numbers field, type BankingBot.
      3. Click the Call button or press Enter.
      4. Follow the bot prompts.

      Learn more

      Summary

      Congratulations! You are now set up and ready to route voice interactions to an Amazon Lex V2 bot that you call with Genesys Cloud Architect. You can also use the Amazon Lex V2 bot to steer interactions and set up escalation to a live agent in Genesys Cloud.