Amazon Lex

(1)

Amazon Lex

V2 Developer Guide

(2)

Amazon Lex: V2 Developer Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What is Amazon Lex V2?

Amazon Lex V2 is an AWS service for building conversational interfaces for applications using voice and text. Amazon Lex V2 provides the deep functionality and ﬂexibility of natural language understanding (NLU) and automatic speech recognition (ASR) so you can build highly engaging user experiences with lifelike, conversational interactions, and create new categories of products.

Amazon Lex V2 enables any developer to build conversational bots quickly. With Amazon Lex V2, no deep learning expertise is necessary—to create a bot, you specify the basic conversation ﬂow in the Amazon Lex V2 console. Amazon Lex V2 manages the dialog and dynamically adjusts the responses in the conversation. Using the console, you can build, test, and publish your text or voice chatbot. You can then add the conversational interfaces to bots on mobile devices, web applications, and chat platforms (for example, Facebook Messenger).

Amazon Lex V2 provides integration with AWS Lambda, and you can integrate with many other services on the AWS platform, including Amazon Connect, Amazon Comprehend, and Amazon Kendra.

Integration with Lambda provides bots access to pre-built serverless enterprise connectors to link to data in SaaS applications such as Salesforce.

Amazon Lex V2 provides the following beneﬁts:

• Simplicity – Amazon Lex V2 guides you through using the console to create your own bot in minutes.

You supply a few example phrases, and Amazon Lex V2 builds a complete natural language model through which the bot can interact using voice and text to ask questions, get answers, and complete sophisticated tasks.

• Democratized deep learning technologies – Amazon Lex V2 provides ASR and NLU technologies to create a Speech Language Understanding (SLU) system. Through SLU, Amazon Lex V2 takes natural language speech and text input, understands the intent behind the input, and fulﬁlls the user intent by invoking the appropriate business function.

Speech recognition and natural language understanding are some of the most challenging problems to solve in computer science, requiring sophisticated deep learning algorithms to be trained on massive amounts of data and infrastructure. Amazon Lex V2 puts deep learning technologies within reach of all developers. Amazon Lex V2 bots convert incoming speech to text and understand the user intent to generate an intelligent response so you can focus on building your bots with added value for your customers and deﬁne entirely new categories of products made possible through conversational interfaces.

• Seamless deployment and scaling – With Amazon Lex V2, you can build, test, and deploy your bots directly from the Amazon Lex V2 console. Amazon Lex V2 enables you to publish your voice or text bots for use on mobile devices, web apps, and chat services (for example, Facebook Messenger).

Amazon Lex V2 scales automatically. You don’t need to worry about provisioning hardware and managing infrastructure to power your bot experience.

• Built-in integration with the AWS platform – Amazon Lex V2 operates natively with other AWS services, such as AWS Lambda and Amazon CloudWatch. You can take advantage of the power of the AWS platform for security, monitoring, user authentication, business logic, storage, and mobile app development.

(8)

Are You a First-time User of Amazon Lex V2?

• Cost-eﬀectiveness – With Amazon Lex V2, there are no upfront costs or minimum fees. You are charged only for the text or speech requests that are made. The pay-as-you-go pricing and the low cost per request make the service a cost-eﬀective way to build conversational interfaces. With the Amazon Lex V2 free tier, you can easily try Amazon Lex V2 without any initial investment.

Are You a First-time User of Amazon Lex V2?

If you are a ﬁrst-time user of Amazon Lex V2, we recommend that you read the following sections in order:

1.How it works (p. 3) – This section introduces Amazon Lex V2 and the features that you use to create a chatbot.

2.Getting started with Amazon Lex V2 (p. 7) – In this section, you set up your account and test Amazon Lex V2.

3.API reference (p. 223) – This section provides additional examples that you can use to explore Amazon Lex V2.

(9)

How it works

Amazon Lex V2 enables you to build applications using a text or speech interface for a conversation with a user. Following are the typical steps for working with Amazon Lex V2:

1. Create a bot and add one or more languages. Conﬁgure the bot so that it understands the user's goal, engages in conversation with the user to elicit information, and fulﬁlls the user's intent.

2. Test the bot. You can use the test window client provided by the Amazon Lex V2 console.

3. Publish a version and create an alias.

4. Deploy the bot. You can deploy the bot on your own applications or messaging platforms such as Facebook Messenger or Slack

Before you get started, familiarize yourself with the following Amazon Lex V2 core concepts and terminology:

• Bot – A bot performs automated tasks such as ordering a pizza, booking a hotel, ordering ﬂowers, and so on. An Amazon Lex V2 bot is powered by automatic speech recognition (ASR) and natural language understanding (NLU) capabilities.

Amazon Lex V2 bots can understand user input provided with text or speech and converse natural language.

• Language – An Amazon Lex V2 bot can converse in one or more languages. Each language is independent of the others, you can conﬁgure Amazon Lex V2 to converse with a user using native words and phrases. For more information, see Languages and locales supported by Amazon Lex V2 (p. 4).

• Intent – An intent represents an action that the user wants to perform. You create a bot to support one or more related intents. For example, you might create an intent that orders pizzas and drinks. For each intent, you provide the following required information:

• Intent name – A descriptive name for the intent. For example, OrderPizza.

• Sample utterances – How a user might convey the intent. For example, a user might say "Can I order a pizza" or "I want to order a pizza."

• How to fulfill the intent – How you want to fulfill the intent after the user provides the necessary information. We recommend that you create a Lambda function to fulfill the intent.

You can optionally conﬁgure the intent so Amazon Lex V2 returns the information back to the client application for the necessary fulﬁllment.

In addition to custom intents, Amazon Lex V2 provides built-in intents to quickly set up your bot. For more information, see Built-in intents and slot types (p. 24).

Amazon Lex always includes a fallback intent for each bot. The fallback intent is used whenever Amazon Lex can't deduce the user's intent. For more information, see AMAZON.FallbackIntent (p. 25).

• Slot – An intent can require zero or more slots, or parameters. You add slots as part of the intent configuration. At runtime, Amazon Lex V2 prompts the user for specific slot values. The user must provide values for all required slots before Amazon Lex V2 can fulfill the intent.

For example the OrderPizza intent requires slots such as size, crust type, and number of pizzas. For each slot, you provide the slot type and one or more prompts that Amazon Lex V2 sends to the client to elicit values from the user. A user can reply with a slot value that contains additional words, such as

"large pizza please" or "let's stick with small." Amazon Lex V2 still understands the slot value.

(10)

Supported languages

• Slot type – Each slot has a type. You can create your own slot type, or you can use built-in slot types.

For example, you might create and use the following slot types for the OrderPizza intent:

• Size – With enumeration values Small, Medium, and Large.

• Crust – With enumeration values Thick and Thin.

Amazon Lex V2 also provides built-in slot types. For example, AMAZON.Number is a built-in slot type that you can use for the number of pizzas ordered. For more information, see Built-in intents and slot types (p. 24).

• Version – A version is a numbered snapshot of your work that you can publish for use in diﬀerent parts of your workﬂow, such as development, beta deployment, and production. Once you create a version, you can use a bot as it existed when the version was made. After you create a version, it stays the same while you continue to work on your application.

• Alias – An alias is a pointer to a speciﬁc version of a bot. With an alias, you can update the version the your client applications are using. For example, you can point an alias to version 1 of your bot.

When you are ready to update the bot, you publish version 2 and change the alias to point to the new version. Because your applications use the alias instead of a speciﬁc version, all of your clients get the new functionality without needing to be updated.

For a list of the AWS Regions where Amazon Lex V2 is available, see Amazon Lex V2 endpoints and quotas in the Amazon Web Services General Reference.

Languages and locales supported by Amazon Lex V2

Amazon Lex V2 supports a variety of languages and locales. The languages supported and the features they support are listed in the following tables.

Supported languages and locales

Amazon Lex V2 supports the following languages and locales.

Code Language and locale

ca_ES Catalan (Spain)

de_AT German (Austria)

de_DE German (Germany)

en_AU English (Australia)

en_GB English (UK)

en_IN English (India)

en_US English (US)

en_ZA English (South Africa)

es_419 Spanish (Latin America)

es_ES Spanish (Spain)

(11)

Code Language and locale

es_US Spanish (US)

fr_CA French (Canada)

fr_FR French (France)

it_IT Italian (Italy)

ja_JP Japanese (Japan)

ko_KR Korean (Korea)

pt_BR Portuguese (Brazil)

pt_PT Portuguese (Portugal)

zh_CN Mandarin (PRC)

Languages and locales supported by Amazon Lex V2 features

All Amazon Lex V2 features are supported in all languages and locales except as listed in this table.

Feature Supported languages and locales

AMAZON.AlphaNumeric (p. 36) All languages and locales except Korean (ko_KR) AMAZON.KendraSearchIntent (p. 27) English (US) (en_US)

Creating a custom vocabulary to improve speech

recognition (p. 59) English (GB) (en_GB)

Automated Chatbot Designer English (US) (en_US)

Polly voice output All languages and locales except Catalan (Spain) (ca_ES)

Region availability All languages and locales are available in all Regions except Catalan (Spain) (ca_ES) Portuguese (Brazil) (pt_BR), Portuguese (Portugal), (pt_PT) and Mandarin (PRC) (zh_CN) are not available in the following Regions:

• Asia Paciﬁc (Singapore) (ap-southeast-1)

• Africa (Cape Town) (ap-south-1) Setting intent context (p. 94) English (US) (en_US)

Using a custom grammar slot type (p. 43) English (Australia) (en_AU) English (UK) (en_GB) English (US) (en_US) Using multiple values in a slot (p. 62) English (US) (en_US)

(12)

Languages and locales supported by Amazon Lex V2 features

Feature Supported languages and locales

Using runtime hints to improve recognition of slot

values (p. 112) English (UK) (en_GB)

Using spelling styles to capture slot

values (p. 114) English (UK) (en_GB)

English (US) (en_US) Using voice transcription conﬁdence

scores (p. 105) English (UK) (en_GB)

English (US) (en_US)

(13)

Getting started with Amazon Lex V2

Amazon Lex V2 provides API operations that you can integrate with your existing applications. For a list of supported operations, see the API reference (p. 223). You can use any of the following options:

• AWS SDK — When using the SDKs your requests to Amazon Lex V2 are automatically signed and authenticated using the credentials that you provide. We recommend that you use an SDK to build your application.

• AWS CLI — You can use the AWS CLI to access any Amazon Lex V2 feature without having to write any code.

• AWS Console — The console is the easiest way to get started testing and using Amazon Lex V2

If you are new to Amazon Lex V2, we recommend that you read How it works (p. 3) ﬁrst.

Topics

• Step 1: Set Up an AWS Account and Create an Administrator User (p. 7)

• Step 2: Getting started (Console) (p. 8)

Step 1: Set Up an AWS Account and Create an Administrator User

Before you use Amazon Lex V2 for the ﬁrst time, complete the following tasks:

1.Sign Up for AWS (p. 7) 2.Create an IAM User (p. 8)

Sign Up for AWS

If you already have an AWS account, skip this task.

When you sign up for Amazon Web Services (AWS), your AWS account is automatically signed up for all services in AWS, including Amazon Lex V2. You are charged only for the services that you use.

With Amazon Lex V2, you pay only for the resources that you use. If you are a new AWS customer, you can get started with Amazon Lex V2 for free. For more information, see AWS Free Usage Tier.

If you already have an AWS account, skip to the next task. If you don't have an AWS account, use the following procedure to create one.

To create an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

(14)

Create an IAM User

Part of the sign-up procedure involves receiving a phone call and entering a veriﬁcation code on the phone keypad.

Write down your AWS account ID because you'll need it for the next task.

Create an IAM User

Services in AWS, such as Amazon Lex V2, require that you provide credentials when you access them so that the service can determine whether you have permissions to access the resources owned by that service. The console requires your password. You can create access keys for your AWS account to access the AWS CLI or API.

However, we don't recommend that you access AWS using the credentials for your AWS account. Instead, we recommend that you:

• Use AWS Identity and Access Management (IAM) to create an IAM user

• Add the user to an IAM group with administrative permissions

• Grant administrative permissions to the IAM user that you created.

You can then access AWS using a special URL and the IAM user's credentials.

The Getting Started exercises in this guide assume that you have a user (adminuser) with administrator privileges. Follow the procedure to create adminuser in your account.

To create an administrator user and sign in to the console

1. Create an administrator user called adminuser in your AWS account. For instructions, see Creating Your First IAM User and Administrators Group in the IAM User Guide.

2. As a user, you can sign in to the AWS Management Console using a special URL. For more information, How Users Sign In to Your Account in the IAM User Guide.

For more information about IAM, see the following:

• AWS Identity and Access Management (IAM)

• Getting started

• IAM User Guide

Next step

Step 2: Getting started (Console) (p. 8)

Step 2: Getting started (Console)

The easiest way to learn how to use Amazon Lex V2 is by using the console. To get you started, we created the following exercises, all of which use the console:

• Exercise 1 — Create an Amazon Lex V2 bot using a blueprint, a predeﬁned bot that provides all of the necessary bot conﬁguration. You do only a minimum of work to test the end-to-end setup.

(15)

• Exercise 2 — Review the JSON structures sent between your client application and an Amazon Lex V2 bot.

Topics

• Exercise 1: Create a bot from an example (p. 9)

• Exercise 2: Review the conversation ﬂow (p. 10)

Exercise 1: Create a bot from an example

In this exercise, you create your ﬁrst Amazon Lex V2 bot and test it in the Amazon Lex V2 console. For this exercise, you use the OrderFlowers example.

Example overview

You use the OrderFlowers example to create an Amazon Lex V2 bot. For more information about the structure of a bot, see How it works (p. 3).

• Intent – OrderFlowers

• Slot types – One custom slot type called FlowerTypes with enumeration values: roses, lilies, and tulips.

• Slots – The intent requires the following information (that is, slots) before the bot can fulﬁll the intent.

• PickupTime (AMAZON.TIME built-in type)

• FlowerType (FlowerTypes custom type)

• PickupDate (AMAZON.DATE built-in type)

• Utterance – The following sample utterances indicate the user's intent:

• "I would like to pick up ﬂowers."

• "I would like to order some ﬂowers."

• Prompts – After the bot identiﬁes the intent, it uses the following prompts to ﬁll the slots:

• Prompt for the FlowerType slot – "What type of ﬂowers would you like to order?"

• Prompt for the PickupDate slot – "What day do you want the {FlowerType} to be picked up?"

• Prompt for the PickupTime slot – "At what time do you want the {FlowerType} to be picked up?"

• Conﬁrmation statement – "Okay, your {FlowerType} will be ready for pickup by {PickupTime} on {PickupDate}. Does this sound okay?"

To create an Amazon Lex V2 bot (Console)

1. Sign in to the AWS Management Console and open the Amazon Lex V2 console at https://

console.aws.amazon.com/lexv2/home 2. Choose Create bot.

3. For the Creation method, choose Start with an example.

4. In the Example bots section, choose OrderFlowers from the list.

5. In the Bot conﬁguration section give the bot a name and a description. The name must be unique in your account.

6. In the Permissions section, choose Create a new role with basic Amazon Lex permissions. This will create an AWS Identity and Access Management (IAM) role with the permissions that Amazon Lex V2 needs to run your bot.

(16)

Exercise 2: Review the conversation ﬂow

8. In the Session timeout and Advanced settings sections, leave the defaults.

9. Choose Next. Amazon Lex V2 creates your bot.

After you create your bot, you must add one or more languages that the bot supports. A language contains the intents, slot types, and slots that the bot uses to converse with users.

To add a language to a bot

1. In the Language section, choose a supported language, and add a description.

2. Leave the Voice interaction and Intent classification confidence score threshold fields with their defaults.

3. Choose Add language to add the language to the bot.

4. After the language is added, choose Done to continue.

After you choose Done, the console opens the intent editor. You can use the intent editor to examine the intents used by the bot. When you are done examining the bot, you can test to bot.

To test the OrderFlowers bot

1. From the bottom menu, choose Build. Wait for the bot to build.

2. When the build is complete, choose Test to open the test window.

3. Test the bot. Start the conversation with one of the sample utterances, such as "I would like to pick up ﬂowers."

Next steps

Now that you've created you ﬁrst bot using a template, you can use the console to create your own bot.

For instruction on creating a custom bot, and for more information about creating bots, see Building bots (p. 17).

Exercise 2: Review the conversation ﬂow

In this exercise you review the JSON structures that are sent between your client application and the Amazon Lex V2 bot that you created in Exercise 1: Create a bot from an example (p. 9).

The conversation uses the RecognizeText (p. 545) operation to generate the JSON structures. The RecognizeUtterance (p. 552) returns the same information as HTTP headers in the response.

The JSON structures are divided by each turn of the conversation. A turn is a request from the client application and a response from the bot.

Turn 1

During the ﬁrst turn of the conversation, the client application initiates the conversation with your bot.

Both the URI and the body of the request provide information about the request.

POST /bots/botId/botAliases/botAliasId/botLocales/localeId/sessions/sessionId/text HTTP/1.1 Content-type: application/json

{ "text": "I would like to order flowers"

}

(17)

• The URI identifies the bot that the client application is communicating with. It also includes a session identifier generated by the client application that identifies a specific conversation between a user and the bot.

• The body of the request contains the text that the user typed to the client application. In this case, only the text is sent, however you application can send additional information, such as request attributes or session state. For more information, see the RecognizeText (p. 545) operation.

From text, Amazon Lex V2 detects the user's intent, to order ﬂowers. Amazon Lex V2 chooses one of the intent's slots (FlowerType) and one of the prompts for the slot, and then sends the following response to the client application. The client displays the response to the user.

{ "interpretations": [ {

"intent": {

"confirmationState": "None", "name": "OrderFlowers", "slots": {

"FlowerType": null, "PickupDate": null, "PickupTime": null },

"state": "InProgress"

},

"nluConfidence": { "score": 0.95 }

}, {

"intent": {

"name": "FallbackIntent", "slots": {}

} } ],

"messages": [ {

"content": "What type of flowers would you like to order?", "contentType": "PlainText"

} ],

"sessionId": "bf445a49-7165-4fcd-9a9c-a782493fba5c", "sessionState": {

"dialogAction": {

"slotToElicit": "FlowerType", "type": "ElicitSlot"

},

"intent": {

"FlowerType": null, "PickupDate": null, "PickupTime": null },

},

"originatingRequestId": "9e8add70-4106-4a10-93f5-2ce2cb959e5f"

} }

(18)

Turns 2 and 3

In turn 2 and 3, the user responds to prompts from the Amazon Lex V2 bot with values that ﬁll the FlowerType and PickupDate slots.

The URI for the second and third turns is the same as the ﬁrst.

{

"text": "1 dozen roses"

}

The response for turn 2 shows the FlowerType slot ﬁlled and provides a prompt to elicit the next slot value.

"intent": {

"FlowerType": { "value": {

"interpretedValue": "dozen roses", "originalValue": "dozen roses", "resolvedValues": []

} },

"PickupDate": null, "PickupTime": null },

},

}, {

"intent": {

} } ],

"messages": [ {

"content": "What day do you want the dozen roses to be picked up?", "contentType": "PlainText"

} ],

"dialogAction": {

"slotToElicit": "PickupDate", "type": "ElicitSlot"

},

"intent": {

"FlowerType": {

(19)

"value": {

} },

"PickupDate": null, "PickupTime": null },

},

} }

Turn 4

In turn 4, the user provides the ﬁnal slot value for the intent, the time that the ﬂowers are picked up.

{ "text": "5 in the evening"

}

In the response, Amazon Lex V2 sends a conﬁrmation prompt to the user to conﬁrm that the order is correct. The dialogAction is set to ConfirmIntent and the confirmationState is None.

"intent": {

} },

"PickupDate": { "value": {

"interpretedValue": "2021-01-04", "originalValue": "next monday", "resolvedValues": [

"2021-01-04"

] } },

"PickupTime": { "value": {

"interpretedValue": "17:00", "originalValue": "5 evening", "resolvedValues": [

"17:00"

] } } },

(20)

},

}, {

"intent": {

} } ],

"messages": [ {

"content": "Okay, your dozen roses will be ready for pickup by 17:00 on 2021-01-04. Does this sound okay?",

"contentType": "PlainText"

} ],

"dialogAction": {

"type": "ConfirmIntent"

},

"intent": {

} },

"2021-01-04"

] } },

"17:00"

] } } },

},

} }

Turn 5

In the ﬁnal turn, the user responds with to the conﬁrmation prompt.

(21)

{ "text": "yes"

}

In the response, Amazon Lex V2 sends indicates that the intent has been fulﬁlled by setting the confirmationState to Confirmed and the dialogAction to close. All of the slot values are available to the client application.

"intent": {

"confirmationState": "Confirmed", "name": "OrderFlowers",

"slots": {

} },

"2021-01-04"

] } },

"17:00"

] } } },

"state": "Fulfilled"

},

}, {

"intent": {

} } ],

"messages": [ {

"content": "Thanks. ", "contentType": "PlainText"

} ],

"dialogAction": {

(22)

"type": "Close"

},

"intent": {

"confirmationState": "Confirmed", "name": "OrderFlowers",

"slots": {

} },

"2021-01-04"

] } },

"17:00"

] } } },

"state": "Fulfilled"

},

} }

(23)

Building bots

You create an Amazon Lex V2 bot to interact with your users to elicit information to accomplish a task.

For example, you can create a bot that gathers the information needed to order a bouquet of ﬂowers or book a hotel room.

To build a bot, you need the following information:

1. The language that the bot uses to interact with the customer. You can choose one or more languages, each language contains independent intents, slots, and slot types.

2. The intents, or goals, that the bot will help the user fulﬁll. A bot can contain one or more intents, such as ordering ﬂowers, or booking a hotel and rental car. You need to decide which statements, or utterances, that the user makes to trigger the intent.

3. The information, or slots, that you need to gather from the user to fulfill an intent. For example, you might need to get the type of flowers from the user or the start date of a hotel reservation. You need to define one or more prompts that Amazon Lex V2 uses to elicit the slot value from the user.

4. The type of the slots that you need from the user. You may need to create a custom slot type, such as a list of ﬂowers that a user can order, or you can use a built-in slot type, such as using the AMAZON.Date slot type for the start date of a reservation.

5. The interactions between user and intents. Amazon Lex V2 manages the interactions; you can create an AWS Lambda function to validate and fulﬁll the intent.

Topics

• Creating a bot (p. 17)

• Adding a language (p. 18)

• Adding intents (p. 18)

• Adding slot types (p. 19)

• Testing a bot using the console (p. 20)

• Creating versions (p. 23)

• Built-in intents and slot types (p. 24)

• Using a custom grammar slot type (p. 43)

• Creating custom slot types (p. 58)

• Creating a custom vocabulary to improve speech recognition (p. 59)

• Using multiple values in a slot (p. 62)

• Using an AWS Lambda function (p. 63)

Creating a bot

Start creating your bot by deﬁning the name, description and some basic information.

To create a bot

console.aws.amazon.com/lexv2/home 2. Choose Create bot.

3. In the Creation method section, choose Create.

4. In the Bot conﬁguration section, give the bot a name and an optional description.

(24)

Adding a language

5. In the IAM permissions section, choose an AWS Identity and Access Management (IAM) role that provides Amazon Lex V2 permission to access other AWS services, such as Amazon CloudWatch.

You can have Amazon Lex V2 create the role, or you can choose an existing role with CloudWatch permissions.

6. In the Children's Online Privacy Protection Act (COPPA) section, choose the appropriate response.

7. In the Idle session timeout section, choose the duration that Amazon Lex V2 keeps a session with a user open. Amazon Lex V2 maintains session variables for the duration of the session so that your bot can resume a conversation with the same variables.

8. In the Advanced settings section add tags that help identify the bot, and can be used to control access and monitor resources.

9. Choose Next to create the bot and move to adding a language.

Adding a language

You add one or more languages and locales to your bot to enable it to communicate with users in their languages. You deﬁne the intents, slots, and slot types separately for each language so that the utterances, prompts, and slot values are speciﬁc to the language.

Your bot must contain at least one language.

To add a language to your bot

1. In the New language section, choose the language that you want to use. You can add a description to help identify the language in lists.

2. If your bot supports voice interaction, in the Voice interaction section, choose the Amazon Polly voice that Amazon Lex V2 uses to communicate with the user. If your bot doesn't support voice, choose None.

3. For the Intent classiﬁcation conﬁdence score threshold, set the value that Amazon Lex V2 uses to determine whether an intent is the correct intent. You can adjust this value after testing your bot.

4. Choose Add.

Adding intents

Intents are the goals that your users want to fulﬁll, such as ordering ﬂowers or booking a hotel. Your bot needs to have at least one intent.

By default, all bots contain a single built-in intent, the fallback intent. This intent is used when Amazon Lex V2 does not recognize any other intent. For example, if a user says "I want to order ﬂowers" to a hotel booking intent, the fallback intent is triggered.

To add an intent

console.aws.amazon.com/lexv2/

2. From the list of bots, choose the bot that you want to add the intent to, then from Add languages choose View languages.

3. Choose the language to add the intent to, then choose Intents.

4. Choose Add intent, give your intent a name, and then choose Add.

5. In the intent editor, add the details of your intent.

• Conversation flow – Use the conversation flow diagram to see how a dialog with your bot might look. You can choose different sections of the conversation to jump to that section of the intent editor.

(25)

• Intent details – Give the intent a name and description to help identify the purpose of the intent.

You can also see the unique identiﬁer that Amazon Lex V2 assigned to the intent.

• Contexts – Set the input and output contexts for the intent. A context is a state variable associated with an intent. An output context is set when an intent is fulﬁlled. An intent with an input context can only be recognized with the context is active. An intent with no input contexts can always be recognized.

• Sample utterances – You should provide 10 or more phrases that you expect your users to use to trigger an intent. Amazon Lex V2 generalizes from these phrases to recognize that the user wants to trigger the intent.

• Slots – Define the slots, or parameters, required to fulfill the intent. Each slot has a type that defines the values that can be entered in the slot. You can choose from your custom slot types, or you can choose a built-in slot type.

• Confirmation prompts and declination responses – These responses are used to end the conversation with a user and to confirm or decline fulfillment of the intent. The confirmation prompt asks the user to review slot values. For example, "I've booked a hotel room for Friday. Is this correct?" The declination response is sent to the user when they decline the confirmation.

• Fulfillment updates – Response sent to the user at the start of fulfillment and periodically while the fulfillment is in progress. For example, "I'm changing your password, this may take a few minutes" and "I'm still working on your request." Fulfillment updates are used only for streaming conversations. For more information, see Configuring fulfillment progress updates (p. 138).

• Post fulfillment status – Response sent to the user when an intent is fulfilled. You can set a success message, a failure message, and a timeout message. You can send post-fulfillment messages for both streaming and regular conversations. For example, if the fulfillment succeeds, you can send "I've changed your password." If the fulfillment doesn't succeed, you can send a response with more information, such as "I couldn't change your password, contact the help desk for assistance." If the fulfillment takes too long to process and exceeds the configured timeout period, you can send a message informing the user, such as "Our servers are very busy right not. Try your request again later." For more information, see Configuring fulfillment progress updates (p. 138).

• Closing responses – Response sent to the user after the intent is fulﬁlled and all other messages are played. For example, a thank you for booking a hotel room. Or it can prompt the user to start a diﬀerent intent, such as "Thank you for booking a room, would you like to book a rental car?"

• Codehooks – Indicate whether you are using an AWS Lambda function to initialize the intent, validate user input, and to fulﬁll the intent. You specify the Lambda function in the alias that you use to run the bot.

6. Choose Save intent to save the intent.

Turning oﬀ responses

While using your bot, you may find it necessary to turn off start and update responses, post-fulfillment responses, confirmation prompts, and closing responses. Responses can be turned on and off for each intent.

Use the Active toggle to determine whether or not to use a response.

Adding slot types

Slot types define the values that users can supply for your intent variables. You define slot types for each language so that the values are specific to that language. For example, for a slot type that lists paint colors, you could include the value "red" in English, "rouge" in French, and "rojo" in Spanish.

(26)

Testing a bot

This topic describes how to create custom slot types that provide values for your intent's slots. You can also use built-in slot types for standard values. For example, you can use the built-in slot type AMAZON.Country for a list of countries in the world.

To create a slot type

2. From the list of bots, choose the bot that you want to add the language to, then choose Conversation structure and then All languages.

3. Choose the language to add the slot type to, then choose Slot types.

4. Choose Add slot type, give your slot type a name, and then choose Add.

5. In the slot type editor, add the details of your slot type.

• Slot value resolution – Determines how slot values are resolved. If you choose Expand values, Amazon Lex V2 uses the values as representative values for training. If you use Restrict to slot values the allowed values for the slot are restricted to the ones that you provide.

• Slot type values – The values for the slot. If you chose Restrict to slot values, you can add synonyms for the value. For example, for the value "football" you can add the synonym "soccer." If the user enters "soccer" in a conversation with your bot, the actual value of the slot is "football."

• Use slot values as custom vocabulary – Enable this option to help improve recognition of slot values and synonyms in audio conversations. Don't enable this option when the slot values are common terms, such as "yes," "no," "one," "two, "three," etc.

6. Choose Save slot type.

Testing a bot using the console

The Amazon Lex V2 console contains a test window that you can use to test the interaction with your bot. You use the test window to have a test conversation with your bot and to see the responses that your application receives from the bot.

There are two types of testing that you can perform with your bot. The ﬁrst, express testing, enables you to test your bot with the exact phrases that you used for creating the bot. For example, if you added the utterance "I want to pick up ﬂowers" to your intent, you can test the bot using that exact phrase.

The second type, complete testing, enables you to test your bot using phrases related to the utterances that you conﬁgured. For example, you can use the phrase "Can I order ﬂowers" to start a conversation with your bot.

You test a bot using a speciﬁc alias and language. If you are testing the development version of the bot, you use the TestBotAlias alias for testing.

To open the test window

2. Choose the bot to test from the list of bots.

3. From the left menu, choose Aliases.

4. From the list of aliases, choose the alias to test.

5. From Languages, choose the radio button of the language to test, and then choose Test.

After you choose Test, the test window opens in the console. You can use the test window to interact with your bot, as shown in the following graphic.

(27)

In addition to the conversation, you can also choose Inspect in the test window to see the responses returned from the bot. The ﬁrst view shows you a summary of the information returned from your bot to the test window.

(28)

Testing a bot

You can also use the test inspection window to see the JSON structures that are sent between the bot and the test window. You can see both the request from the test window and the response from Amazon Lex V2.

(29)

Creating versions

Amazon Lex V2 supports publishing versions of bots so that you can control the implementation that your client applications use. A version is a numbered snapshot of your work that you can publish for use in diﬀerent parts of your workﬂow, such as development, beta deployment, and production.

The Draft version

When you create an Amazon Lex V2 bot there is only one version, the Draft version.

Draft is the working copy of your bot. You can update only the Draft version and until you publish your ﬁrst version, Draft is the only version of the bot that you have.

(30)

Creating a version

The Draft version of your bot is associated with the TestBotAlias. The TestBotAlias should only be used for manual testing. Amazon Lex V2 limits the number of runtime requests that you can make to the TestBotAlias alias of the bot.

Creating a version

When you version an Amazon Lex V2 bot you create a numbered snapshot of the bot so that you can use the bot as it existed when the version was made. Once you've created a numeric version it will stay the same while you continue to work on the draft version of your application.

When you create a version, you can choose the locales to include in the version. You don't need to choose all of the locales in a bot. Also, when you create a version you can choose a locale from a previous version. For example, if you have three versions of a bot, you can choose one locale from the Draft version and one from version two when you create version four.

If you delete a locale from the Draft version, it is not deleted from a numbered version.

If a bot version is not used for six months, Amazon Lex V2 will mark the version inactive. When a version is inactive, you can't use runtime operations with the bot. To make the bot active, rebuild all the languages associated with the version.

Updating an Amazon Lex V2 bot

You can update only the Draft version of an Amazon Lex V2 bot. Versions can't be changed.

You can publish a new version any time after you update a resource in the console or with the CreateBotVersion (p. 246) operation.

Deleting an Amazon Lex V2 bot or version

Amazon Lex V2 supports deleting a bot or version using the console or one of the API operations:

• DeleteBot (p. 303)

• DeleteBotVersion (p. 312)

Built-in intents and slot types

To make it easier to create bots, Amazon Lex V2 allows you to use standard built-in intents and slot types.

Topics

• Built-in intents (p. 24)

• Built-in slot types (p. 35)

Built-in intents

For common actions, you can use the standard built-in intents library. To create an intent from a built-in intent, choose a built-intent in the console, and give it a new name. The new intent has the conﬁguration of the base intent, such as the sample utterances.

In the current implementation, you can't do the following:

• Add or remove sample utterances from the base intent

• Conﬁgure slots for built-in intents

(31)

To add a built-in intent to a bot

2. Choose the bot to add the built-in intent to.

3. In the left menu, choose the language and then choose Intents.

4. Choose Add intent, and then choose Use built-in intent.

5. In Built-in intent, choose the intent to use.

6. Give the intent a name, and then choose Add.

7. Use the intent editor to conﬁgure the intent as required for your bot.

Topics

• AMAZON.CancelIntent (p. 25)

• AMAZON.FallbackIntent (p. 25)

• AMAZON.HelpIntent (p. 26)

• AMAZON.KendraSearchIntent (p. 27)

• AMAZON.PauseIntent (p. 34)

• AMAZON.RepeatIntent (p. 34)

• AMAZON.ResumeIntent (p. 34)

• AMAZON.StartOverIntent (p. 35)

• AMAZON.StopIntent (p. 35)

AMAZON.CancelIntent

Responds to words and phrases that indicate the user wants to cancel the current interaction. Your application can use this intent to remove slot type values and other attributes before ending the interaction with the user.

Common utterances:

• cancel

• never mind

• forget it

AMAZON.FallbackIntent

When a user's input to an intent isn't what a bot expects, you can conﬁgure Amazon Lex V2 to invoke a fallback intent. For example, if the user input "I'd like to order candy" doesn't match an intent in your OrderFlowers bot, Amazon Lex V2 invokes the fallback intent to handle the response.

The built-in AMAZON.FallbackIntent intent type is added to your bot automatically when you create a bot using the console, when you use the API you can specify the intent using the CreateBot (p. 230) operation.

Invoking a fallback intent uses two steps. In the ﬁrst step the fallback intent is matched based on the input from the user. When the fallback intent is matched, the way the bot behaves depends on the number of retries conﬁgured for a prompt.

Amazon Lex V2 matches the fallback intent in these situations:

• The user's input to an intent doesn't match the input that the bot expects

(32)

Built-in intents

• Audio input is noise, or text input isn't recognized as words.

• The user's input is ambiguous and Amazon Lex V2 can't determine which intent to invoke.

The fallback intent is invoked when:

• The bot doesn't recognize the user input as an intent after the conﬁgured number of tries for clariﬁcation when the conversation is started.

• An intent doesn't recognize the user input as a slot value after the conﬁgured number of tries.

• An intent doesn't recognize the user input as a response to a conﬁrmation prompt after the conﬁgured number of tries.

You can't add the following to a fallback intent:

• Utterances

• Slots

• A conﬁrmation prompt

Using a Lambda Function with a Fallback Intent

When a fallback intent is invoked, the response depends on the setting of the fulfillmentCodeHook parameter to the CreateIntent (p. 254) operation. The bot does one of the following:

• Returns the intent information to the client application.

• Calls the aliases's validation and fulﬁllment Lambda function. It calls the function with the session variables that are set for the session.

For more information about setting the response when a fallback intent is invoked, see the fulfillmentCodeHook parameter of the CreateIntent (p. 254) operation.

If you use the Lambda function with your fallback intent, you can use this function to call another intent or to perform some form of communication with the user, such as collecting a callback number or opening a session with a customer service representative.

A fallback intent can be invoked multiple times in the same session. For example, suppose that your Lambda function uses the ElicitIntent dialog action to prompt the user for a different intent. If Amazon Lex V2 can't infer the user's intent after the configured number of tries, it invokes the fallback intent again. It also invokes the fallback intent when the user doesn't respond with a valid slot value after the configured number of tries.

You can conﬁgure your Lambda function to keep track of the number of times that the fallback intent is called using a session variable. Your Lambda function can take a diﬀerent action if it is called more times than the threshold that you set in your Lambda function. For more information about session variables, see Setting session attributes (p. 96).

AMAZON.HelpIntent

Responds to words or phrases that indicate the user needs help while interacting with your bot. When this intent is invoked, you can conﬁgure your Lambda function or application to provide information about the your bot's capabilities, ask follow up questions about areas of help, or hand the interaction over to a human agent.

Common utterances:

• help

(33)

• help me

• can you help me

AMAZON.KendraSearchIntent

To search documents that you have indexed with Amazon Kendra, use the

AMAZON.KendraSearchIntent intent. When Amazon Lex V2 can't determine the next action in a conversation with the user, it triggers the search intent.

The AMAZON.KendraSearchIntent is available only in the English (US) (en-US) locale and in the US East (N. Virginia), US West (Oregon) and Europe (Ireland) Regions.

Amazon Kendra is a machine-learning-based search service that indexes natural language documents such as PDF documents or Microsoft Word ﬁles. It can search indexed documents and return the following types of responses to a question:

• An answer

• An entry from a FAQ that might answer the question

• A document that is related to the question

For an example of using the AMAZON.KendraSearchIntent, see Example: Creating a FAQ Bot for an Amazon Kendra Index (p. 32).

If you conﬁgure an AMAZON.KendraSearchIntent intent for your bot, Amazon Lex V2 calls the intent whenever it can't determine the user utterance for a slot or intent. For example, if your bot is eliciting a response for a slot type called "pizza topping" and the user says "What is a pizza?," Amazon Lex V2 calls the AMAZON.KendraSearchIntent to handle the question. If there is no response from Amazon Kendra, the conversation continues as conﬁgured in the bot.

When you use the AMAZON.KendraSearchIntent with the AMAZON.FallbackIntent in the same bot, Amazon Lex V2 uses the intents as follows:

1. Amazon Lex V2 calls the AMAZON.KendraSearchIntent. The intent calls the Amazon Kendra Query operation.

2. If Amazon Kendra returns a response, Amazon Lex V2 displays the result to the user.

3. If there is no response from Amazon Kendra, Amazon Lex V2 re-prompts the user. The next action depends on response from the user.

• If the response from the user contains an utterance that Amazon Lex V2 recognizes, such as filling a slot value or confirming an intent, the conversation with the user proceeds as configured for the bot.

• If the response from the user does not contain an utterance that Amazon Lex V2 recognizes, Amazon Lex V2 makes another call to the Query operation.

4. If there is no response after the conﬁgured number of retries, Amazon Lex V2 calls the AMAZON.FallbackIntent and ends the conversation with the user.

There are three ways to use the AMAZON.KendraSearchIntent to make a request to Amazon Kendra:

• Let the search intent make the request for you. Amazon Lex V2 calls Amazon Kendra with the user's utterance as the search string. When you create the intent, you can define a query filter string that limits the number of responses that Amazon Kendra returns. Amazon Lex V2 uses the filter in the query request.

• Add additional query parameters to the request to narrow the search results using your Lambda function. You add a kendraQueryFilterString ﬁeld that contains Amazon Kendra query

parameters to the delegate dialog action. When you add query parameters to the request with the

(34)

Built-in intents

Lambda function, they take precedence over the query ﬁlter that you deﬁned when you created the intent.

• Create a new query using the Lambda function. You can create a complete Amazon Kendra query request that Amazon Lex V2 sends. You specify the query in the kendraQueryRequestPayload field in the delegate dialog action. The kendraQueryRequestPayload field takes precedence over the kendraQueryFilterString field.

To specify the queryFilterString parameter when you create a bot, or to specify the

kendraQueryFilterString field when you call the delegate action in a dialog Lambda function, you specify a string that is used as the attribute filter for the Amazon Kendra query. If the string isn't a valid attribute filter, you'll get an InvalidBotConfigException exception at runtime. For more information about attribute filters, see Using document attributes to filter queries in the Amazon Kendra Developer Guide.

To have control over the query that Amazon Lex V2 sends to Amazon Kendra, you can specify a query in the kendraQueryRequestPayloadﬁeld in your Lambda function. If the query isn't valid, Amazon Lex V2 returns an InvalidLambdaResponseException exception. For more information, see the Query operation in the Amazon Kendra Developer Guide.

For an example of how to use the AMAZON.KendraSearchIntent, see Example: Creating a FAQ Bot for an Amazon Kendra Index (p. 32).

IAM Policy for Amazon Kendra Search

To use the AMAZON.KendraSearchIntent intent, you must use a role that provides AWS Identity and Access Management (IAM) policies that enable Amazon Lex V2 to assume a runtime role that has permission to call the Amazon Kendra Query intent. The IAM settings that you use depend on whether you create the AMAZON.KendraSearchIntent using the Amazon Lex V2 console, or using an AWS SDK or the AWS Command Line Interface (AWS CLI). When you use the console, you can choose between adding permission to call Amazon Kendra to the Amazon Lex V2 service-linked role or using a role speciﬁcally for calling the Amazon Kendra Query operation. When you use the AWS CLI or an SDK to create the intent, you must use a role speciﬁcally for calling the Query operation.

Attaching Permissions

You can use the console to attach permissions to access the Amazon Kendra Query operation to the default Amazon Lex V2 service-linked role. When you attach permissions to the service-linked role, you don't have to create and manage a runtime role speciﬁcally to connect to the Amazon Kendra index.

The user, role, or group that you use to access the Amazon Lex V2 console must have permissions to manage role policies. Attach the following IAM policy to the console access role. When you grant these permissions, the role has permissions to change the existing service-linked role policy.

{ "Version": "2012-10-17", "Statement": [

{

"Effect": "Allow", "Action": [

"iam:AttachRolePolicy", "iam:PutRolePolicy", "iam:GetRolePolicy"

],

"Resource": "arn:aws:iam::*:role/aws-service-role/lexv2.amazonaws.com/

AWSServiceRoleForLexBots*"

}, {

"Effect": "Allow",

"Action": "iam:ListRoles", "Resource": "*"

(35)

} ] }

Specifying a Role

You can use the console, the AWS CLI, or the API to specify a runtime role to use when calling the Amazon Kendra Query operation.

The IAM user, role, or group that you use to specify the runtime role must have the iam:PassRole permission. The following policy deﬁnes the permission. You can use the

iam:AssociatedResourceArn and iam:PassedToService condition context keys to further limit the scope of the permissions. For more information, see IAM and AWS STS Condition Context Keys in the AWS Identity and Access Management User Guide.

{

"Version": "2012-10-17", "Statement": [

{

"Effect": "Allow", "Action": "iam:PassRole",

"Resource": "arn:aws:iam::account:role/role"

} ] }

The runtime role that Amazon Lex V2 needs to use to call Amazon Kendra must have the kendra:Query permissions. When you use an existing IAM role for permission to call the Amazon Kendra Query

operation, the role must have the following policy attached.

You can use the IAM console, the IAM API, or the AWS CLI to create a policy and attach it to a role. These instructions use the AWS CLI to create the role and policies.

NoteThe following code is formatted for Linux and MacOS. For Windows, replace the Linux line continuation character (\) with a caret (^).

To add Query operation permission to a role

1. Create a document called KendraQueryPolicy.json in the current directory, add the following code to it, and save it

{ "Version": "2012-10-17", "Statement": [

{

"Effect": "Allow", "Action": [

"kendra:Query"

],

"Resource": [

"arn:aws:kendra:region:account:index/index ID"

] } ] }

2. In the AWS CLI, run the following command to create the IAM policy for running the Amazon Kendra Query operation.

aws iam create-policy \

Amazon Lex

Amazon Lex

V2 Developer Guide

Amazon Lex: V2 Developer Guide

Table of Contents

What is Amazon Lex V2?

Are You a First-time User of Amazon Lex V2?

How it works

Languages and locales supported by Amazon Lex V2

Supported languages and locales

Languages and locales supported by Amazon Lex V2 features

Getting started with Amazon Lex V2

Step 1: Set Up an AWS Account and Create an Administrator User

Sign Up for AWS

Create an IAM User

Next step

Step 2: Getting started (Console)

Exercise 1: Create a bot from an example

Example overview

Next steps

Exercise 2: Review the conversation ﬂow

Turn 1

Turns 2 and 3

Turn 4

Turn 5

Building bots

Creating a bot

Adding a language

Adding intents

Turning oﬀ responses

Adding slot types

Testing a bot using the console

Creating versions

The Draft version

Creating a version

Updating an Amazon Lex V2 bot

Deleting an Amazon Lex V2 bot or version

Built-in intents and slot types

Built-in intents

AMAZON.CancelIntent

AMAZON.FallbackIntent

Using a Lambda Function with a Fallback Intent

AMAZON.HelpIntent

AMAZON.KendraSearchIntent

IAM Policy for Amazon Kendra Search