Amazon Lex
Developer Guide

Managing Conversation Context

Conversation context is the information that a user shares with Amazon Lex to fulfill an intent. This can be slot data that your user provides and session attributes that are created by the client application and Lambda functions. This topic explains the following:

Setting Session Timeout

For each Amazon Lex bot, you can configure the session timeout, the length of time that a conversation session lasts. For each in-progress conversation, Amazon Lex retains context information, slot data and session attributes, until the session ends. By default, the session duration is five minutes, but you can specify any duration between 0 and 1,440 minutes (24 hours).

For example, suppose that you create a ShoeOrdering bot that supports intents such as OrderShoes and GetOrderStatus. When Amazon Lex detects that the user's intent is to order shoes, it asks the user for slot data. For example, it would ask for shoe size, color, brand, etc. If the user provides some of the slot data but doesn't complete the shoe purchase, Amazon Lex remembers all of the slot data and session attributes for the duration of the session. If the user returns before the session expires, he or she can provide the remaining slot data, and complete the purchase.

Set the session timeout when you create a bot using the Amazon Lex console. Or, set it in the AWS command line interface (AWS CLI) when you create or update a bot with the PutBot operation by setting the idleSessionTTLInSeconds field.

Setting Session Attributes

Session attributes are application-specific information passed between Amazon Lex and a client application using the sessionAttributes field in the PostContent or the PostText request and response. Amazon Lex passes session attributes to all Lambda functions configured for a bot. If a Lambda function adds or updates session attributes, Amazon Lex passes the new information back to the client application. For example:

Use session attributes in your Lambda functions to initialize and customize prompts and response cards. For example:

  • Initialization — In a pizza ordering bot, the client application passes the user's location as a session attribute in the first call to the PostContent or PostText operation. For example, "Location": "111 Maple Street". The Lambda function uses this information to find the closest pizzeria to place the order.

  • Personalize prompts — Configure prompts to refer to session attributes, for example, "Hey [FirstName], what toppings would you like?" If you pass the user's first name as a session attribute ("{FirstName": "Jo"}), Amazon Lex substitutes the session attribute for the placeholder to send a personalized prompt to the user, "Hey Jo, which toppings would you like?"

Session attributes persist for the duration of the session. Amazon Lex stores them in an encrypted data store until the session ends. The client can create session attributes in a request by calling either the PostContent or the PostText operation with the sessionAttributes field set to a value. A Lambda function can create a session attribute in a response. After the client or a Lambda function establishes a session attribute, the attribute is used any time that the sessionAttribute field is not included in a request to Amazon Lex.

For example, suppose session attributes {"x": 1, "y": 2} have been created for a session. If the client makes a subsequent call to the PostContent or PostText operation without specifying the sessionAttributes field, Amazon Lex calls the Lambda function with the stored session attributes ({"x": 1, "y": 2}). If the Lambda function doesn't return session attributes, Amazon Lex returns the stored session attributes back to the client application.

If either the client application or a Lambda function passes session attributes, Amazon Lex updates the stored session attributes. Passing an existing value, such as {"x": 2}, updates the stored value. When an empty map, {}, is passed, stored values are erased.

Sharing Information Between Intents

Amazon Lex supports sharing information between intents. To share across intents, you use session attributes.

For example, a user of the ShoeOrdering bot starts by ordering shoes. Amazon Lex engages in a conversation with the user, gathering slot data, such as shoe size, color, and brand. When the user places an order, the Lambda function that fulfills the order sets the orderNumber session attribute, which contains the order number. To get the status of the order, the user uses the GetOrderStatus intent. Amazon Lex can ask the user for slot data, such as order number and order date. Once Amazon Lex has the required information, it can return the status of the order.

However, if you think that your users might switch intents during the same session, you can design your bot to return the status of the latest order. Instead of asking the user for order information again, you can use the orderNumber session attribute to share information across intents and fulfill the GetOrderStatus intent by returning the status of the last order that the user placed.

For an example of cross-intent information sharing, see Example Bot: BookTrip.