Amazon Lex - Developer Guide

378 Pages·2017·4.07 MB·English

Amazon Lex
Developer Guide
Amazon Lex Developer Guide
Amazon Lex: Developer Guide
Copyright © 2022 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
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 affiliated with, connected to, or sponsored by Amazon.
Amazon Lex Developer Guide
Table of Contents
...................................................................................................................................................... vii
What Is Amazon Lex? ......................................................................................................................... 1
Are You a First-time User of Amazon Lex? ..................................................................................... 2
How It Works.................................................................................................................................... 3
Supported Languages................................................................................................................. 5
Supported Languages and Locales ....................................................................................... 5
Languages and Locales Supported by Amazon Lex Features ..................................................... 5
Programming Model................................................................................................................... 5
Model Building API Operations............................................................................................ 6
Runtime API Operations...................................................................................................... 7
Lambda Functions As Code Hooks........................................................................................ 7
Managing Messages.................................................................................................................. 10
Types of Messages ............................................................................................................ 10
Contexts for Configuring Messages ..................................................................................... 11
Supported Message Formats .............................................................................................. 15
Message Groups............................................................................................................... 15
Response Cards................................................................................................................ 16
Managing Conversation Context ................................................................................................. 20
Setting Intent Context ...................................................................................................... 20
Using Default Slot Values .................................................................................................. 22
Setting Session Attributes ................................................................................................. 23
Setting Request Attributes ................................................................................................ 24
Setting the Session Timeout .............................................................................................. 26
Sharing Information Between Intents .................................................................................. 26
Setting Complex Attributes ............................................................................................... 27
Using Confidence Scores ........................................................................................................... 28
Session Management........................................................................................................ 29
Conversation Logs.................................................................................................................... 30
IAM Policies for Conversation Logs ..................................................................................... 30
Configuring Conversation Logs ........................................................................................... 33
Encrypting Conversation Logs ............................................................................................ 35
Viewing Text Logs in Amazon CloudWatch Logs ................................................................... 36
Accessing Audio Logs in Amazon S3 ................................................................................... 39
Monitoring Conversation Log Status with CloudWatch Metrics ................................................ 39
Managing Sessions................................................................................................................... 40
Switching Intents............................................................................................................. 41
Resuming a Prior Intent .................................................................................................... 41
Starting a New Session ..................................................................................................... 42
Validating Slot Values ....................................................................................................... 42
Deployment Options................................................................................................................. 42
Built-in Intents and Slot Types ................................................................................................... 42
Built-in Intents................................................................................................................. 43
Built-in Slot Types ............................................................................................................ 54
Custom Slot Types................................................................................................................... 62
Slot Obfuscation...................................................................................................................... 63
Sentiment Analysis................................................................................................................... 64
Tagging Resources.................................................................................................................... 65
Tagging Your Resources .................................................................................................... 65
Tag Restrictions................................................................................................................ 66
Tagging Resources (Console) .............................................................................................. 66
Tagging Resources (AWS CLI) ............................................................................................. 67
Getting Started ................................................................................................................................ 69
Step 1: Set Up an Account ........................................................................................................ 69
Sign Up for AWS .............................................................................................................. 69
iii
Amazon Lex Developer Guide
Create an IAM User .......................................................................................................... 70
Next Step........................................................................................................................ 70
Step 2: Set Up the AWS CLI ....................................................................................................... 70
...................................................................................................................................... 71
Step 3: Getting Started (Console)............................................................................................... 71
Exercise 1: Create a Bot Using a Blueprint ........................................................................... 72
Exercise 2: Create a Custom Bot ......................................................................................... 98
Exercise 3: Publish a Version and Create an Alias ................................................................ 109
Step 4: Getting Started (AWS CLI) ............................................................................................ 110
Exercise 1: Create a Bot ................................................................................................... 110
Exercise 2: Add a New Utterance ...................................................................................... 122
Exercise 3: Add a Lambda Function ................................................................................... 126
Exercise 4: Publish a Version ............................................................................................ 129
Exercise 5: Create an Alias ............................................................................................... 133
Exercise 6: Clean Up ....................................................................................................... 134
Versioning and Aliases.................................................................................................................... 135
Versioning............................................................................................................................. 135
The $LATEST Version ...................................................................................................... 135
Publishing an Amazon Lex Resource Version ...................................................................... 136
Updating an Amazon Lex Resource ................................................................................... 136
Deleting an Amazon Lex Resource or Version ..................................................................... 136
Aliases................................................................................................................................... 137
Using Lambda Functions................................................................................................................. 139
Lambda Function Input Event and Response Format ................................................................... 139
Input Event Format ......................................................................................................... 139
Response Format............................................................................................................ 144
Amazon Lex and AWS Lambda Blueprints .................................................................................. 149
Updating a Blueprint for a Specific Locale......................................................................... 149
Deploying Bots............................................................................................................................... 150
Deploying an Amazon Lex Bot on a Messaging Platform .............................................................. 150
Integrating with Facebook ............................................................................................... 152
Integrating with Kik........................................................................................................ 154
Integrating with Slack..................................................................................................... 157
Integrating with Twilio SMS ............................................................................................. 162
Deploying an Amazon Lex Bot in Mobile Applications .................................................................. 164
Importing and Exporting ................................................................................................................. 165
Exporting and Importing in Amazon Lex Format ......................................................................... 165
Exporting in Amazon Lex Format ...................................................................................... 165
Importing in Amazon Lex Format ..................................................................................... 166
JSON Format for Importing and Exporting ......................................................................... 167
Exporting to an Alexa Skill ...................................................................................................... 170
Bot Examples................................................................................................................................. 171
Schedule Appointment............................................................................................................ 171
Overview of the Bot Blueprint (ScheduleAppointment) ........................................................ 173
Overview of the Lambda Function Blueprint (lex-make-appointment-python) ......................... 174
Step 1: Create an Amazon Lex Bot .................................................................................... 174
Step 2: Create a Lambda Function .................................................................................... 176
Step 3: Update the Intent: Configure a Code Hook .............................................................. 177
Step 4: Deploy the Bot on the Facebook Messenger Platform ............................................... 178
Details of Information Flow ............................................................................................. 178
Book Trip............................................................................................................................... 189
Step 1: Blueprint Review ................................................................................................. 191
Step 2: Create an Amazon Lex Bot .................................................................................... 192
Step 3: Create a Lambda function .................................................................................... 195
Step 4: Add the Lambda Function as a Code Hook .............................................................. 195
Details of the Information Flow ........................................................................................ 198
Example: Using a Response Card .............................................................................................. 211
iv
Amazon Lex Developer Guide
Updating Utterances............................................................................................................... 214
Integrating with a Web site ..................................................................................................... 215
Call Center Agent Assistant ...................................................................................................... 215
Step 1: Create an Amazon Kendra Index ............................................................................ 217
Step 2: Create an Amazon Lex Bot .................................................................................... 217
Step 3: Add a Custom and Built-in Intent .......................................................................... 217
Step 4: Set up Amazon Cognito ....................................................................................... 218
Step 5: Deploy Your Bot as a Web Application .................................................................... 219
Step 6: Use the Bot........................................................................................................ 220
Migrating a bot.............................................................................................................................. 222
Migrating a bot (Console) ........................................................................................................ 222
Migrating a Lambda function ................................................................................................... 223
Migration messages................................................................................................................ 223
Built-in intent................................................................................................................ 223
Built-in slot type ............................................................................................................ 223
Conversation logs........................................................................................................... 224
Message groups.............................................................................................................. 224
Prompts and phrases ...................................................................................................... 224
Other Amazon Lex V1 features ......................................................................................... 224
Migrating a Lambda function ................................................................................................... 225
List of updated fields...................................................................................................... 226
Security......................................................................................................................................... 232
Data Protection...................................................................................................................... 232
Encryption at Rest .......................................................................................................... 233
Encryption in Transit ....................................................................................................... 234
Key Management............................................................................................................ 234
Identity and Access Management .............................................................................................. 234
Audience....................................................................................................................... 234
Authenticating with Identities.......................................................................................... 235
Managing Access Using Policies ........................................................................................ 236
Learn More.................................................................................................................... 237
How Amazon Lex Works with IAM .................................................................................... 238
Identity-Based Policy Examples ........................................................................................ 242
AWS managed policies .................................................................................................... 246
Troubleshooting............................................................................................................. 252
Using Service-Linked Roles ...................................................................................................... 254
Service-Linked Roles Permissions for Amazon Lex ............................................................... 254
Creating a Service-Linked Role for Amazon Lex .................................................................. 254
Editing a Service-Linked Role for Amazon Lex .................................................................... 254
Deleting a Service-Linked Role for Amazon Lex .................................................................. 255
Supported Regions for Amazon Lex Service-Linked Roles ..................................................... 255
Monitoring............................................................................................................................. 255
Monitoring Amazon Lex with CloudWatch .......................................................................... 255
Logging Amazon Lex API Calls with AWS CloudTrail ............................................................ 263
Compliance Validation............................................................................................................. 266
Resilience.............................................................................................................................. 267
Infrastructure Security............................................................................................................. 267
Guidelines and Quotas.................................................................................................................... 268
Supported Regions................................................................................................................. 268
General Guidelines.................................................................................................................. 268
Quotas.................................................................................................................................. 270
Runtime Service Quotas .................................................................................................. 271
Model Building Quotas................................................................................................... 272
API Reference................................................................................................................................. 276
Actions.................................................................................................................................. 276
Amazon Lex Model Building Service .................................................................................. 277
Amazon Lex Runtime Service ........................................................................................... 427
v
Amazon Lex Developer Guide
Data Types............................................................................................................................ 458
Amazon Lex Model Building Service .................................................................................. 459
Amazon Lex Runtime Service ........................................................................................... 505
Document History.......................................................................................................................... 519
AWS glossary................................................................................................................................. 524
vi
Amazon Lex Developer Guide
We recommend using Amazon Lex V2 to take advantage of the latest features. Documentation for
Amazon Lex V2 may be found here.
vii
Amazon Lex Developer Guide
What Is Amazon Lex?
Amazon Lex is an AWS service for building conversational interfaces for applications using voice and
text. With Amazon Lex, the same conversational engine that powers Amazon Alexa is now available
to any developer, enabling you to build sophisticated, natural language chatbots into your new and
existing applications. Amazon Lex provides the deep functionality and flexibility 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 enables any developer to build conversational chatbots quickly. With Amazon Lex, no deep
learning expertise is necessary—to create a bot, you just specify the basic conversation flow in the
Amazon Lex console. Amazon Lex manages the dialogue 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 provides pre-built integration with AWS Lambda, and you can easily integrate with many
other services on the AWS platform, including Amazon Cognito, AWS Mobile Hub, Amazon CloudWatch,
and Amazon DynamoDB. Integration with Lambda provides bots access to pre-built serverless enterprise
connectors to link to data in SaaS applications, such as Salesforce, HubSpot, or Marketo.
Some of the benefits of using Amazon Lex include:
• Simplicity – Amazon Lex guides you through using the console to create your own chatbot in minutes.
You supply just a few example phrases, and Amazon Lex 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 – Powered by the same technology as Alexa, Amazon
Lex provides ASR and NLU technologies to create a Speech Language Understanding (SLU) system.
Through SLU, Amazon Lex takes natural language speech and text input, understands the intent
behind the input, and fulfills 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 puts deep learning technologies within reach
of all developers, powered by the same technology as Alexa. Amazon Lex chatbots convert incoming
speech to text and understand the user intent to generate an intelligent response, so you can focus on
building your bots with differentiated value-add for your customers, to define entirely new categories
of products made possible through conversational interfaces.

• Seamless deployment and scaling – With Amazon Lex, you can build, test, and deploy your chatbots
directly from the Amazon Lex console. Amazon Lex enables you to easily publish your voice or text
chatbots for use on mobile devices, web apps, and chat services (for example, Facebook Messenger).
Amazon Lex scales automatically so 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 has native interoperability with other AWS
services, such as Amazon Cognito, AWS Lambda, Amazon CloudWatch, and AWS Mobile Hub. You
1
Amazon Lex Developer Guide
Are You a First-time User of Amazon Lex?
can take advantage of the power of the AWS platform for security, monitoring, user authentication,
business logic, storage, and mobile app development.

• Cost-effectiveness – With Amazon Lex, 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-effective way to build conversational interfaces. With the Amazon Lex
free tier, you can easily try Amazon Lex without any initial investment.
Are You a First-time User of Amazon Lex?
If you are a first-time user of Amazon Lex, we recommend that you read the following sections in order:
1. Getting Started with Amazon Lex (p. 69) – In this section, you set up your account and test
Amazon Lex.
2. API Reference (p. 276) – This section provides additional examples that you can use to explore
Amazon Lex.
2
Amazon Lex Developer Guide
Amazon Lex: How It Works
Amazon Lex enables you to build applications using a speech or text interface powered by the same
technology that powers Amazon Alexa. Following are the typical steps you perform when working with
Amazon Lex:
1. Create a bot and configure it with one or more intents that you want to support. Configure the bot so
it understands the user's goal (intent), engages in conversation with the user to elicit information, and
fulfills the user's intent.
2. Test the bot. You can use the test window client provided by the Amazon Lex console.
3. Publish a version and create an alias.
4. Deploy the bot. You can deploy the bot on platforms such as mobile applications or messaging
platforms such as Facebook Messenger.
Before you get started, familiarize yourself with the following Amazon Lex core concepts and
terminology:
• Bot – A bot performs automated tasks such as ordering a pizza, booking a hotel, ordering flowers, and
so on. An Amazon Lex bot is powered by Automatic Speech Recognition (ASR) and Natural Language
Understanding (NLU) capabilities. Each bot must have a unique name within your account.

Amazon Lex bots can understand user input provided with text or speech and converse in natural
language. You can create Lambda functions and add them as code hooks in your intent configuration
to perform user data validation and fulfillment tasks.

• 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 a bot that orders pizza and drinks. For each
intent, you provide the following required information:

• Intent name– A descriptive name for the intent. For example, OrderPizza. Intent names must be
unique within your account.
• Sample utterances – How a user might convey the intent. For example, a user might say "Can I order
a pizza please" 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 (for example, place order with a local pizza shop). We recommend that you create a
Lambda function to fulfill the intent.

You can optionally configure the intent so Amazon Lex simply returns the information back to the
client application to do the necessary fulfillment.

In addition to custom intents such as ordering a pizza, Amazon Lex also provides built-in intents to
quickly set up your bot. For more information, see Built-in Intents and Slot Types (p. 42).

3