Amazon Lex
Developer Guide

Programming Model

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 the user input to Amazon Lex using one of the runtime API operations. Users can provide speech or text input.

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:

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


  • 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, according to the intent configuration.

For example, the test window in the Amazon Lex console uses the PostContent API to send 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:

  • Customize 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.

  • Validate 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.

  • Fulfill 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:

                    The Amazon Lex console showing Lambda function code hooks.

You can also set the code hooks using the dialogCodeHook and fulfillmentActivity fields in thePutIntent operation.

One Lambda function can do 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 execute the appropriate portion of your code.

For more information, see Using Lambda Functions.