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

Managing Sessions With the Amazon Lex API

When a user starts a conversation with your bot, Amazon Lex creates a session. The information exchanged between your application and Amazon Lex makes up the session state for the conversation. When you make a request, the session is identified by a combination of the bot name and a user identifier that you specify. For more information about the user identifier, see the userId field in the PostContent or PostText operation.

The response from a session operation includes a unique session identifier that identifies a specific session with a user. You can use this identifier during testing or to help troubleshoot your bot.

You can modify the session state sent between your application and your bot. For example, you can create and modify session attributes that contain custom information about the session, and you can change the flow of the conversation by setting the dialog context to interpret the next utterance.

There are two ways that you can update session state. The first is to use a Lambda function with the PostContent or PostText operation that is called after each turn of the conversation. For more information, see Using Lambda Functions. The other is to use the Amazon Lex runtime API in your application to make changes to the session state.

The Amazon Lex runtime API provides operations that enable you to manage session information for a conversation with your bot. The operations are the PutSession operation, the GetSession operation, and the DeleteSession operation. You use these operations to get information about the state of your user's session with your bot, and to have fine-grained control over the state.

Use the GetSession operation when you want to get the current state of the session. The operation returns the current state of the session, including the state of the dialog with your user, any session attributes that have been set and slot values for the last three intents that the user interacted with.

The PutSession operation enables you to directly manipulate the current session state. You can set the type of dialog action that the bot will perform next. This gives you control over the flow of the conversation with the bot. Set the dialog action type field to Delegate to have Amazon Lex determine the next action for the bot.

You can use the PutSession operation to create a new session with a bot and set the intent that the bot should start with. You can also use the PutSession operation to change from one intent to another. When you create a session or change the intent you also can set session state, such as slot values and session attributes. When the new intent is finished, you have the option of restarting the prior intent. You can use the GetSession operation to get the dialog state of the prior intent from Amazon Lex and use the information to set the dialog state of the intent.

The response from the PutSession operation contains the same information as the PostContent operation. You can use this information to prompt the user for the next piece of information, just as you would with the response from the PostContent operation.

Use the DeleteSession operation to remove an existing session and start over with a new session. For example, when you are testing your bot you can use the DeleteSession operation to remove test sessions from your bot.

The session operations work with your fulfillment Lambda functions. For example, if your Lambda function returns Failed as the fulfillment state you can use the PutSession operation to set the dialog action type to close and fulfillmentState to ReadyForFulfillment to retry the fulfillment step.

Here are some things that you can do with the session operations:

Each of these are described further below.

Switching Intents

You can use the PutSession operation to switch from one intent to another. You can also use it to switch back to a previous intent. You can use the PutSession operation to set session attributes or slot values for the new intent.

Resuming a Prior Intent

To resume a prior intent you use the GetSession operation to get the summary of the intent, and then use the PutSession operation to set the intent to its previous dialog state.

In some cases it may be necessary to resume your user's conversation with your bot. For example, say that you have created a customer service bot. Your application determines that the user needs to talk to a customer service representative. After talking to the user, the representative can direct the conversation back to the bot with the information that they collected.

To resume a session, use steps similar to these:

You can use the PutSession operation checkpointLabel parameter to label an intent so that you can find it later. For example, a bot that asks a customer for information might go into a Waiting intent while the customer gathers the information. The bot creates a checkpoint label for the current intent and then starts the Waiting intent. When the customer returns the bot can find the previous intent using the checkpoint label and switch back.

The intent must be present in the recentIntentSummaryView structure returned by the GetSession operation. If you specify a checkpoint label in the GetSession operation request, it will return a maximum of three intents with that checkpoint label.

Starting a New Session

If you want to have the bot start the conversation with your user, you can use the PutSession operation.

Validating Slot Values

You can validate responses to your bot using your client application. If the response isn't valid, you can use the PutSession operation to get a new response from your user. For example, suppose that your flower ordering bot can only sell tulips, roses, and lilies. If the user orders carnations, your application can do the following: