Menu
Amazon Lex
Developer Guide

Lambda Function Input Event and Response Format

This section describes the structure of the event data that Amazon Lex provides to a Lambda function. Use this information to parse the input in your Lambda code. It also explains the format of the response that Amazon Lex expects your Lambda function to return.

Input Event Format

The following shows the general format of an Amazon Lex event that is passed to a Lambda function. Use this information when you are writing your Lambda function.

Note

The input format may change without a corresponding change in the messageVersion. Your code should not throw an error if new fields are present.

Copy
{ "currentIntent": { "name": "intent-name", "slots": { "slot-name": "value", "slot-name": "value", "slot-name": "value" }, "confirmationStatus": "None, Confirmed, or Denied (intent confirmation, if configured)", }, "bot": { "name": "bot-name", "alias": "bot-alias", "version": "bot-version" }, "userId": "User ID specified in the POST request to Amazon Lex.", "inputTranscript": "Text used to process the request", "invocationSource": "FulfillmentCodeHook or DialogCodeHook", "outputDialogMode": "Text or Voice, based on ContentType request header in runtime API request", "messageVersion": "1.0", "sessionAttributes": { "key1": "value1", "key2": "value2" } }

Note the following additional information about the event fields:

  • currentIntent – Provides the intent name, slots, and confirmationStatus fields.

     

    Slots provides a list of slots that are configured for the intent and values that are recognized by Amazon Lex in the user conversation. Otherwise, the values are null.

    Slots is a map of slot names, configured for the intent, to slot values that Amazon Lex has recognized in the user conversation. A slot value remains null until the user provides a value.

     

    A slot value may not match one of the slot values configured for the slot. For example, if the user responds to the prompt "What color car would you like?" with "pizza," Amazon Lex will return "pizza" as the slot type value. Your function should validate the values to make sure that they make sense in context.

     

    confirmationStatus provides the user response to a confirmation prompt, if there is one. For example, if Amazon Lex asks "Do you want to order a large cheese pizza?," depending on the user response, the value of this field can be Confirmed or Denied. Otherwise, this value of this field is None.

     

    If the user confirms the intent, Amazon Lex sets this field to Confirmed. If the user denies the intent, Amazon Lex sets this value to Denied.

     

    In the confirmation response, a user utterance might provide slot updates. For example, the user might say "yes, change size to medium." In this case, the subsequent Lambda event has the updated slot value, PizzaSize set to medium. Amazon Lex sets the confirmationStatus to None, because the user modified some slot data, requiring the Lambda function to perform user data validation.

     

  • bot – Information about the bot that processed the request.

    • name – The name of the bot that processed the request.

    • alias – The alias of the bot version that processed the request.

    • version – The version of the bot that processed the request.

     

  • userId – This value is provided by the client application. Amazon Lex passes it to the Lambda function.

     

  • inputTranscript – The text used to process the request.

    If the input was text, the inputTranscript field contains the text that was input by the user.

     

    If the input was an audio stream, the inputTranscript field contains the text extracted from the audio stream. This is the text that is actually processed to recognize intents and slot values.

     

  • invocationSource – To indicate why Amazon Lex is invoking the Lambda function, it sets this to one of the following values:

    • DialogCodeHook – Amazon Lex sets this value to direct the Lambda function to initialize the function and to validate the user's data input.

       

      When the intent is configured to invoke a Lambda function as an initialization and validation code hook, Amazon Lex invokes the specified Lambda function on each user input (utterance) after Amazon Lex understands the intent.

      Note

      If the intent is not clear, Amazon Lex can't invoke the Lambda function.

       

    • FulfillmentCodeHook – Amazon Lex sets this value to direct the Lambda function to fulfill an intent.

       

      If the intent is configured to invoke a Lambda function as a fulfillment code hook, Amazon Lex sets the invocationSource to this value only after it has all the slot data to fulfill the intent.

       

    In your intent configuration, you can have two separate Lambda functions to initialize and validate user data and to fulfill the intent. You can also use one Lambda function to do both. In that case, your Lambda function can use the invocationSource value to follow the correct code path.

     

  • outputDialogMode – For each user input, the client sends the request to Amazon Lex using one of the runtime API operations, PostContent or PostText. Amazon Lex use the request parameters, Amazon Lex to determine whether the response to the client is text or voice, and sets this field accordingly.

     

    The Lambda function can use this information to generate an appropriate message. For example, if the client expects a voice response, your Lambda function could return Speech Synthesis Markup Language (SSML) instead of text.

     

  • messageVersion – The version of the message that identifies the format of the event data going into the Lambda function and the expected format of the response from a Lambda function.

    Note

    You configure this value when you define an intent. In the current implementation, only message version 1.0 is supported. Therefore, the console assumes the default value of 1.0 and doesn't show the message version.

  • sessionAttributes – Application-specific session attributes that the client sent in the request. If you want Amazon Lex to include them in the response to the client, your Lambda function should send these back to Amazon Lex in the response. For more information, see the runtime API operations, PostContent and PostText.

     

Response Format

Amazon Lex expects a response from a Lambda function in the following format:

Copy
{ "sessionAttributes": { "key1": "value1", "key2": "value2" ... }, "dialogAction": { "type": "ElicitIntent, ElicitSlot, ConfirmIntent, Delegate, or Close", Full structure based on the type field. See below for details. } }

The response consists of two fields. The sessionAttributes field is optional, the dialogAction field is required. The contents of the dialogAction field depends on the value of the type field.For details, see dialogAction.

sessionAttributes

Optional. If you include the sessionAttributes field it can be empty. If you want Amazon Lex to include any session attributes in the response to the client application, your Lambda function must return them in this field. For more information, see the PostContent and PostText operations.

Copy
"sessionAttributes": { "key1": "value1", "key2": "value2" }

dialogAction

Required. The dialogAction field directs Amazon Lex to the next course of action, and describes what to expect from the user after Amazon Lex returns a response to the client.

The type field indicates the next course of action. It also determines the other fields that the Lambda function needs to provide as part of the dialogAction value.

  • Close — Informs Amazon Lex not to expect a response from the user. For example, "Your pizza order has been placed" does not require a response.

     

    The fulfillmentState field is required. Amazon Lex uses this value to set the dialogState in the response to the client application. The message and responseCard fields are optional. If you don't specify a message, Amazon Lex uses the goodbye message or the follow-up message configured for the intent.

    Copy
    "dialogAction": { "type": "Close", "fulfillmentState": "Fulfilled or Failed", "message": { "contentType": "PlainText or SSML", "content": "Message to convey to the user. For example, Thanks, your pizza has been ordered." }, "responseCard": { "version": integer-value, "contentType": "application/vnd.amazonaws.card.generic", "genericAttachments": [ { "title":"card-title", "subTitle":"card-sub-title", "imageUrl":"URL of the image to be shown", "attachmentLinkUrl":"URL of the attachment to be associated with the card", "buttons":[ { "text":"button-text", "value":"Value sent to server on button click" } ] } ] } }
  • ConfirmIntent — Informs Amazon Lex that the user is expected to give a yes or no answer to confirm or deny the current intent.

     

    You must include the intentName and slots fields. The slots field must contain an entry for each of the slots configured for the specified intent. If the value of a slot is unknown, you must set it to null. The message and responseCard fields are optional.

    Copy
    "dialogAction": { "type": "ConfirmIntent", "message": { "contentType": "PlainText or SSML", "content": "Message to convey to the user. For example, Are you sure you want a large pizza?" }, "intentName": "intent-name", "slots": { "slot-name": "value", "slot-name": "value", "slot-name": "value" }, "responseCard": { "version": integer-value, "contentType": "application/vnd.amazonaws.card.generic", "genericAttachments": [ { "title":"card-title", "subTitle":"card-sub-title", "imageUrl":"URL of the image to be shown", "attachmentLinkUrl":"URL of the attachment to be associated with the card", "buttons":[ { "text":"button-text", "value":"Value sent to server on button click" } ] } ] } }
  • Delegate — Directs Amazon Lex to choose the next course of action based on the bot configuration. The response must include any session attributes, and the slots field must include all of the slots specified for the requested intent. If the value of the field is unknown, you must set it to null. You will get a DependencyFailedException exception if your fufillment function returns the Delegate dialog action without removing any slots.

    Copy
    "dialogAction": { "type": "Delegate", "slots": { "slot-name": "value", "slot-name": "value", "slot-name": "value" } }
  • ElicitIntent — Informs Amazon Lex that the user is expected to respond with an utterance that includes an intent. For example, "I want a large pizza," which indicates the OrderPizzaIntent. The utterance "large," on the other hand, is not sufficient for Amazon Lex to infer the user's intent.

     

    The message and responseCard fields are optional. If you don't provide a message, Amazon Lex uses one of the bot's clarification prompts.

    Copy
    { "dialogAction": { "type": "ElicitIntent", "message": { "contentType": "PlainText or SSML", "content": "Message to convey to the user. For example, What can I help you with?" }, "responseCard": { "version": integer-value, "contentType": "application/vnd.amazonaws.card.generic", "genericAttachments": [ { "title":"card-title", "subTitle":"card-sub-title", "imageUrl":"URL of the image to be shown", "attachmentLinkUrl":"URL of the attachment to be associated with the card", "buttons":[ { "text":"button-text", "value":"Value sent to server on button click" } ] } ] } }
  • ElicitSlot — Informs Amazon Lex that the user is expected to provide a slot value in the response.

     

    The intentName, slotToElicit, and slots fields are required. The slots field must include all of the slots specified for the requested intent. The message and responseCard fields are optional. If you don't specify a message, Amazon Lex uses one of the slot elicitation prompts configured for the slot.

    Copy
    "dialogAction": { "type": "ElicitSlot", "message": { "contentType": "PlainText or SSML", "content": "Message to convey to the user. For example, What size pizza would you like?" }, "intentName": "intent-name", "slots": { "slot-name": "value", "slot-name": "value", "slot-name": "value" }, "slotToElicit" : "slot-name", "responseCard": { "version": integer-value, "contentType": "application/vnd.amazonaws.card.generic", "genericAttachments": [ { "title":"card-title", "subTitle":"card-sub-title", "imageUrl":"URL of the image to be shown", "attachmentLinkUrl":"URL of the attachment to be associated with the card", "buttons":[ { "text":"button-text", "value":"Value sent to server on button click" } ] } ] } }