End of support notice: On September 15, 2025, AWS will discontinue support for Amazon Lex V1. After September 15, 2025, you will no longer be able to access the Amazon Lex V1 console or Amazon Lex V1 resources. If you are using Amazon Lex V2, refer to the Amazon Lex V2 guide instead. .
A bot is the primary resource type in Amazon Lex. The other resource types in Amazon Lex are intent, slot type, alias, and bot channel association.
You create a bot using the Amazon Lex console or the model building API. The console provides a graphical user interface that you use to build a production-ready bot for your application. If you prefer, you can use the model building API through the AWS CLI or your own custom program to create a bot.
After you create a bot, you deploy it on one of the supported platforms or integrate it into your own application. When a user interacts with the bot, the client application sends requests to the bot using the Amazon Lex runtime API. For example, when a user says "I want to order pizza," your client sends this input to Amazon Lex using one of the runtime API operations. Users can provide input as speech or text.
You can also create Lambda functions and use them in an intent. Use these Lambda function code hooks to perform runtime activities such as initialization, validation of user input, and intent fulfillment. The following sections provide additional information.
Model Building API
Operations
To programmatically create bots, intents, and slot types, use the model building API operations. You can also use the model building API to manage, update, and delete resources for your bot. The model building API operations include:
-
PutBot, PutBotAlias, PutIntent, and PutSlotType to create and update bots, bot aliases, intents, and slot types, respectively.
-
CreateBotVersion, CreateIntentVersion, and CreateSlotTypeVersion to create and publish versions of your bots, intents, and slot types, respectively.
-
GetBot and GetBots to get a specific bot or a list of bots that you have created, respectively.
-
GetIntent and GetIntents to get a specific intent or a list of intents that you have created, respectively.
-
GetSlotType and GetSlotTypes to get a specific slot type or a list of slot types that you have created, respectively.
-
GetBuiltinIntent, GetBuiltinIntents, and GetBuiltinSlotTypes to get an Amazon Lex built-in intent, a list of Amazon Lex built-in intents, or a list of built-in slot types that you can use in your bot, respectively.
-
GetBotChannelAssociation and GetBotChannelAssociations to get an association between your bot and a messaging platform or a list of the associations between your bot and messaging platforms, respectively.
-
DeleteBot, DeleteBotAlias, DeleteBotChannelAssociation, DeleteIntent, and DeleteSlotType to remove unneeded resources in your account.
You can use the model building API to create custom tools to manage your Amazon Lex resources. For example, there is a limit of 100 versions each for bots, intents, and slot types. You could use the model building API to build a tool that automatically deletes old versions when your bot nears the limit.
To make sure that only one operation updates a resource at a time, Amazon Lex uses
checksums. When you use a Put API operation—PutBot, PutBotAlias
PutIntent, or PutSlotType—to update a
resource, you must pass the current checksum of the resource in the request. If two
tools try to update a resource at the same time, they both provide the same current
checksum. The first request to reach Amazon Lex matches the current checksum of the
resource. By the time that the second request arrives, the checksum is different.
The second tool receives a PreconditionFailedException exception and
the update terminates.
The Get operations—GetBot, GetIntent, and GetSlotType—are eventually consistent. If you use a
Get operation immediately after you create or modify a resource
with one of the Put operations, the changes might not be returned.
After a Get operation returns the most recent update, it always returns
that updated resource until the resource is modified again. You can determine if an
updated resource has been returned by looking at the checksum.
Runtime API Operations
Client applications use the following runtime API operations to communicate with Amazon Lex:
-
PostContent – Takes speech or text input and returns intent information and a text or speech message to convey to the user. Currently, Amazon Lex supports the following audio formats:
Input audio formats – LPCM and Opus
Output audio formats – MPEG, OGG, and PCM
The
PostContentoperation supports audio input at 8 kHz and 16 kHz. Applications where the end user speaks with Amazon Lex over the telephone, such as an automated call center, can pass 8 kHz audio directly. -
PostText – Takes text as input and returns intent information and a text message to convey to the user.
Your client application uses the runtime API to call a specific Amazon Lex bot to
process utterances — user text or voice input. For example, suppose that a
user says "I want pizza." The client sends this user input to a bot using one of the
Amazon Lex runtime API operations. From the user input, Amazon Lex recognizes that the
user request is for the OrderPizza intent defined in the bot. Amazon Lex
engages the user in a conversation to gather the required information, or slot data,
such as pizza size, toppings, and number of pizzas. After the user provides all of
the necessary slot data, Amazon Lex either invokes the Lambda function code hook to
fulfill the intent, or returns the intent data to the client, depending on how the
intent is configured.
Use the PostContent operation when your bot uses speech input. For example, an automated call center application can send speech to an Amazon Lex bot instead of an agent to address customer inquiries. You can use the 8 kHz audio format to send audio directly from the telephone to Amazon Lex.
The test window in the Amazon Lex console uses the PostContent API to send text and speech requests to Amazon Lex. You use this test window in the Getting Started with Amazon Lex exercises.
Lambda Functions As Code Hooks
You can configure your Amazon Lex bot to invoke a Lambda function as a code hook. The code hook can serve multiple purposes:
-
Customizes the user interaction—For example, when Joe asks for available pizza toppings, you can use prior knowledge of Joe's choices to display a subset of toppings.
-
Validates the user's input—Suppose that Jen wants to pick up flowers after hours. You can validate the time that Jen input and send an appropriate response.
-
Fulfills the user's intent—After Joe provides all of the information for his pizza order, Amazon Lex can invoke a Lambda function to place the order with a local pizzeria.
When you configure an intent, you specify Lambda functions as code hooks in the following places:
-
Dialog code hook for initialization and validation—This Lambda function is invoked on each user input, assuming Amazon Lex understood the user intent.
-
Fulfillment code hook—This Lambda function is invoked after the user provides all of the slot data required to fulfill the intent.
You choose the intent and set the code hooks in the Amazon Lex console, as shown in the following screen shot:
You can also set the code hooks using the dialogCodeHook and
fulfillmentActivity fields in the PutIntent operation.
One Lambda function can perform initialization, validation, and fulfillment. The event data that the Lambda function receives has a field that identifies the caller as either a dialog or fulfillment code hook. You can use this information to run the appropriate portion of your code.
You can use a Lambda function to build a bot that can navigate complex dialogs. You
use the dialogAction field in the Lambda function response to direct
Amazon Lex to take specific actions. For example, you can use the ElicitSlot
dialog action to tell Amazon Lex to ask the user for a slot value that isn't required. If
you have a clarification prompt defined, you can use the ElicitIntent
dialog action to elicit a new intent when the user is finished with the previous
one.
For more information, see Using Lambda Functions.
