Menu
Amazon Lex
Developer Guide

Managing Messages (Prompts and Statements)

You configure messages that you want a bot to send when you create the bot. Consider the following examples:

  • You can configure your bot with the following clarification prompt:

    Copy
    I don't understand. What would you like to do?

    Amazon Lex sends this message to the client if it doesn't understand the user's intent.

     

  • Suppose that you create a bot to support an intent called OrderPizza. For a pizza order, you want users to provide information such as pizza size, toppings, and crust type. For example, you can configure prompts such as the following:

    Copy
    What size pizza you want? What toppings you want on the pizza? Do you want thick or thin crust?

    After Amazon Lex determines the user's intent to order pizza, it sends these messages to the client to elicit data from the user.

This section explains designing user interactions in your bot configuration.

Types of Messages

You can classify messages as follows:

  • Prompt – A prompt expects a user response, typically a question.

  • Statement – A statement does not expect a response.

The messages you configure can have dynamic components:

  • Messages can use the following syntax to refer to slot values of the intent that Amazon Lex is currently aware of:

    Copy
    {SlotName}
  • Messages can use the following syntax to refer to session attributes:

    Copy
    [AttributeName]

You can have messages that include both slots and session attributes.

At runtime, Amazon Lex substitutes these references with actual values. For example, suppose that you configure the following message in the OrderPizza intent of your bot:

Copy
"Hey [FirstName], your {PizzaTopping} pizza will arrive in [DeliveryTime] minutes"

This message refers to both slot (PizzaTopping) and session attributes (FirstName and DeliveryTime). At runtime, Amazon Lex replaces these placeholders with values and returns the following message to the client:

Copy
"Hey John, your cheese pizza will arrive in 30 minutes"

For information about session attributes, see the runtime API operations PostText, and PostContent. For an example, see Example Bot: BookTrip.

If you add code hooks using Lambda functions in your intent configuration, you can create messages dynamically. Lambda functions can generate messages and return them to Amazon Lex to send to the user. By providing the messages while configuring your bot, you can eliminate the need to construct a prompt in code hooks.

Contexts for Configuring Messages

You can add messages in the following contexts. Use the Amazon Lex console or build-time API to configure your bot:

  • Bot-level messages – You can configure your bot with clarification prompts and hang-up messages. At runtime, Amazon Lex uses the clarification prompts if it does not understand the user's intent. You can also configure the number of times that Amazon Lex requests clarification before hanging up with a hang-up message. You configure these bot-level messages with the PutBot action, or in the Error Handling section in the Amazon Lex console, as shown in the following screen shot:

     

    Note

    • If you have a Lambda function configured as a code hook for an intent, the Lambda function might return a response directing Amazon Lex to elicit user intent. If the Lambda function does not provide a message to convey to the user, then Amazon Lex uses the clarification prompt you configured.

       

    • Amazon Lex uses the hang-up statement whenever the user doesn't respond with an appropriate answer for a prompt within the maximum permissable attempts. This includes responses to intent elicitations, slot elicitations, follow-up prompts, and intent confirmations. To configure the maximum permissible attempts, use the PutBot action, or, in the console, specify it in the Error Handling section.

       

  • Intent-level messages – You can configure the intent-level messages such as confirmation prompts, cancel statements, goodbye message, and prompts that Amazon Lex can use to elicit slot values, as shown in the following screenshot:

     

    • Confirmation prompts and cancel statements – After a user provides all of the required data, Amazon Lex asks the user for confirmation using the specified message before fulfilling the intent. If the user replies "No" to a confirmation prompt, Amazon Lex returns the cancel statement to the client.

       

    • Goodbye message or follow-up prompts – If you add a Lambda function as a code hook to fulfill the intent, you can configure one of these messages as backup messages. If the Lambda function succeeds but does not provide a message to send to the user, Amazon Lex sends the message that you configured.

       

      • The following is an example of a goodbye message. The example assumes that the application maintains the DeliveryTime session attribute.

        Copy
        "I have placed your order for pizza. It will arrive in [DeliveryTime] minutes."
      • The following is an example of a follow-up prompt:

        Copy
        "I have placed your order for pizza. Do you want me to do anything else?".

        If you configure a follow-up prompt, you must also configure a cancel statement. If the user's reply to a follow-up prompt is a "Yes," Amazon Lex recognizes the user's confirmation and also recognizes the user's intent (OrderDrink), and then follows up accordingly. For example:

        Copy
        "Yes, I also want to order a drink."

        If the user says "No," Amazon Lex sends the cancel statement. For example:

        Copy
        "Alright. Ping me if you need anything else."
    • Prompts to elicit value slot values – You must specify at least one prompt message for each of the required slots in an intent. At runtime, Amazon Lex uses one of these messages to prompt the user to provide value for this slot. For example, for a cityName slot, the following is a valid prompt:

      Copy
      "Which city would you like to fly to?"

    Note

    In a Lambda function that is a code hook for an intent, you can override any of the messages that you configured at build time.

You can configure more than one message for a specific context. At runtime, Amazon Lex picks the message with the maximum possible substitutions. For example, to elicit a value for crust type in the OrderPizza intent, you can configure multiple messages, as follows:

Copy
Hey [FirstName], what topping would you like for your {PizzaSize} pizza? Hey [FirstName], what topping would you like for your pizza? What topping would you like? Tell me the topping you would like on your pizza.

Then, Amazon Lex uses the following order of selection:

  • If both the FirstName session attribute and the PizzaSize slot value are available, Amazon Lex uses the first prompt.

  • If the FirstName session attribute is available, but the PizzaSize slot value isn't, Amazon Lex uses the second prompt.

  • If both the session attribute and the slot value aren't available, Amazon Lex randomly chooses the third or fourth prompt.

At runtime, Amazon Lex disregards messages with references to unresolved slot values. If all of the messages for a given context have unresolved references, Amazon Lex throws a BadRequestException error. We recommend that you have at least one message without references.

Supported Message Formats

Amazon Lex supports messages in the following formats: plain text and Speech Synthesis Markup Language (SSML).

If the output mode is text, such as when a client sends requests using the PostText API operation or the PostContent API operation with the Accept HTTP header set to text/plain; charset=utf-8, Amazon Lex selects only plain text messages. It disregards SSML messages.

Note

  • If you configure your bot with only SSML messages and a text client communicates with your bot, Amazon Lex returns a BadRequestException error. We recommend that you provide at least one PlainText message for each context.

  • If outputDialogMode in the incoming event is text, you must return a PlainText message from your AWS Lambda function. For more information, see Lambda Function Input Event and Response Format.

Amazon Lex also supports synthesizing audio from SSML. For more information, see Using SSML in the Amazon Polly Developer Guide.

Response Cards

For each interaction context, you can also configure a response card. When you configure a response card, Amazon Lex includes the response card with the corresponding message in its response to the client. The client shows the message and displays the response card. The user chooses an option in the response card. For a given context,there can be many messages, but there can only be one response card.

You use response cards with text-based clients that use the PostText operation, including messaging platforms such as Facebook Messenger. You can't use response cards with the PostContent operation.

You configure the value for each option in a response card. For example, in a taxi application, you can configure an option to read "Home" on the response card and set the value to the address "111 Maple Street, Seattle 98101." When the user selects this option, Amazon Lex receives the entire address as the input text. Response cards simplify interaction for your users and increase your bot's accuracy by reducing typographical errors.

You can define response cards statically at build-time or dynamically in a Lambda function at runtime. If you've define both static and dynamic response cards, the dynamic response card takes precedence over the static response card.

Amazon Lex understands the response cards and sends responses in a format understandable to client applications. For example, Amazon Lex transforms the response card to a generic template if the client is Facebook Messenger. For more information, see Generic Template on the Facebook website.

For examples, see the following topics.

Defining Static Response Cards

You can define response cards with the PutBot operation or the Amazon Lex console. Suppose that you are creating a bot with an intent and that one of the slots for this intent is color. When defining the color slot, you specify prompts, as shown in the following console screen shot:

In describing prompts, you can optionally associate a response card and define details with the PutBot action, or, in the Amazon Lex console, as shown in the following example:

Now suppose that you've integrated your bot with Facebook Messenger. The user can click the buttons to choose a color, as shown in the following illustration:

You can refer to session attributes in response cards. At runtime, Amazon Lex substitutes these references with appropriate values from the session attributes.

For an example, see Example: Using a Response Card.

Defining Response Cards Dynamically

To generate response cards dynamically, use a Lambda function as a code hook Amazon Lex generates a response card in response to user input, and returns the details in the dialogAction section of the response. For more information, see Response Format.

The following is an example Lambda function with a partial response showing the responseCard element. It generates a user experience similar to the one shown in the preceding section.

Copy
responseCard: { "version": 1, "contentType": "application/vnd.amazonaws.card.generic", "genericAttachments": [ { "title": "What Color", "subtitle": "What color do you want", "imageUrl: "https://s3.amazonaws.com/lex-box/ice-tea.jpeg", "attachmentLinkUrl: "https://s3.amazonaws.com/lex-box/ice-tea.html", "buttons": [ { "text": "Red", "value": "red" }, { "text": "Green", "value": "green" }, { "text": "Blue", "value": "blue" } ] } ] }

For an example, see Example Bot: ScheduleAppointment.