Using an AWS Lambda function - Amazon Lex

Using an AWS Lambda function

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

Attaching a Lambda function to a bot alias

With Amazon Lex V2 you indicate that an intent should use a Lambda function for each intent. But you assign the Lambda function that your intents use for each language supported by a bot alias. That way you can create a Lambda function tailored to each language that your bot alias supports.

You indicate that an intent should use a Lambda function using the console or the CreateIntent or UpdateIntent operation. In the intent editor, you turn on Lambda functions in the Code hooks section of the editor.


                The code hooks section of the Amazon Lex V2 intent
                    editor.

You define the Lambda function to use in each bot alias. The same Lambda function is used for all intents in a language supported by the bot.

To choose a Lambda function to use with a bot alias

  1. Open the Amazon Lex console at https://console.aws.amazon.com/lexv2/.

  2. From the list of bots, choose the name of the bot that you want to use.

  3. From Create versions and aliases for deployment, choose View aliases.

  4. From the list of aliases, choose the name of the alias that you want to use.

  5. From the list of supported languages, choose the language that the Lambda function is used for.

  6. Choose the name of the Lambda function to use, then choose the version or alias of the function.

  7. Choose Save to save your changes.

Input event format

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

Note

The input format may change without a corresponding change to the messageVersion. Your code shouldn't throw an error if new fields are present.

{ "messageVersion": "1.0", "invocationSource": "DialogCodeHook | FulfillmentCodeHook", "inputMode": "DTMF | Speech | Text", "responseContentType": "CustomPayload | ImageResponseCard | PlainText | SSML", "sessionId": "string", "inputTranscript": "string", "bot": { "id": "string", "name": "string", "aliasId": "string", "localeId": "string", "version": "string" }, "interpretations": [ { "intent": { "confirmationState": "Confirmed | Denied | None", "name": "string", "slots": { "string": { "value": { "interpretedValue": "string", "originalValue": "string", "resolvedValues": [ "string" ] } }, "string": { "shape": "List", "value": { "interpretedValue": "string", "originalValue": "string", "resolvedValues": [ "string" ] }, "values": [ { "shape": "Scalar", "value": { "originalValue": "string", "interpretedValue": "string", "resolvedValues": [ "string" ] } }, { "shape": "Scalar", "value": { "originalValue": "string", "interpretedValue": "string", "resolvedValues": [ "string" ] } } ] } }, "state": "Failed | Fulfilled | FulfillmentInProgress | InProgress | ReadyForFulfillment | Waiting", "kendraResponse": { // Only present when intent is KendraSearchIntent. For details, see // https://docs.aws.amazon.com/kendra/latest/dg/API_Query.html#API_Query_ResponseSyntax } }, "nluConfidence": { "score": number }, "sentimentResponse": { "sentiment": "string", "sentimentScore": { "mixed": number, "negative": number, "neutral": number, "positive": number } } } ], "proposedNextState": { "dialogAction": { "slotToElicit": "string", "type": "Close | ConfirmIntent | Delegate | ElicitIntent | ElicitSlot" }, "intent": { "name": "string", "confirmationState": "Confirmed | Denied | None", "slots": {}, "state": "Failed | Fulfilled | InProgress | ReadyForFulfillment | Waiting" } }, "requestAttributes": { "string": "string" }, "sessionState": { "activeContexts": [ { "name": "string", "contextAttributes": { "string": "string" }, "timeToLive": { "timeToLiveInSeconds": number, "turnsToLive": number } } ], "sessionAttributes": { "string": "string" }, "sessionState": { "intent": {}, "activeContexts": [], "dialogAction": {}, "originatingRequestId": {}, "sessionAttributes": {}, "runtimeHints": { "slotHints": { "string": { "string": { "runtimeHintValues": [ { "phrase": "string" }, { "phrase": "string" } ] } } } } }, "dialogAction": { "slotToElicit": "string", "type": "Close | ConfirmIntent | Delegate | ElicitIntent | ElicitSlot" }, "intent": { "confirmationState": "Confirmed | Denied | None", "name": "string", "slots": { "string": { "value": { "interpretedValue": "string", "originalValue": "string", "resolvedValues": [ "string" ] } }, "string": { "shape": "List", "value": { "interpretedValue": "string", "originalValue": "string", "resolvedValues": [ "string" ] }, "values": [ { "shape": "Scalar", "value": { "originalValue": "string", "interpretedValue": "string", "resolvedValues": [ "string" ] } }, { "shape": "Scalar", "value": { "originalValue": "string", "interpretedValue": "string", "resolvedValues": [ "string" ] } } ] } }, "state": "Failed | Fulfilled | FulfillmentInProgress | InProgress | ReadyForFulfillment | Waiting", "kendraResponse": { // Only present when intent is KendraSearchIntent. For details, see // https://docs.aws.amazon.com/kendra/latest/dg/API_Query.html#API_Query_ResponseSyntax } }, "originatingRequestId": "string" } } }

Note the following additional information about the event fields:

  • invocationSource – Indicates the action that called the Lambda function. When the source is DialogCodeHook, the Lambda function was called after input from the user. When the source is FulfillmentCodeHook the Lambda function was called after all required slots have been filled and the intent is ready for fulfillment.

  • inputTranscript – The text that was used to process the input from the user. For text or DTMF input, this is the text that the user typed. For speech input, this is the text that was recognized from the speech.

  • interpretations – One or more intents that Amazon Lex V2 considers possible matches to the user's utterance. For more information, see Interpretation.

  • proposedNextState – The next state of the dialog between the user and the bot if the Lambda function doesn't change the flow. For more information, see proposedNextState structure.

  • requestAttributes – Request-specific attributes that the client sends in the request. Use request attributes to pass information that doesn't need to persist for the entire session.

  • sessionState – The current state of the conversation between the user and your Amazon Lex V2 bot. For more information about the session state, see SessionState.

proposedNextState structure

The proposedNextState structure contains information about the next action that the bot will take if the Lambda function sets the dialogAction to Delegate. You can use the information to modify your Lambda function's behavior based on what Amazon Lex V2 proposes as the next action.

For example, suppose an intent has slots for first and last names. After filling in the first-name slot, the proposedNextState indicates the slot to elicit in the next turn is the last-name slot, You can query a database for last names associated with the first name and provide the results as runtime hints for the slot. For more information about runtime hints, see Using runtime hints to improve recognition of slot values.

The proposedNextState structure contains the dialog action that Amazon Lex V2 will perform next. It also indicates the slot to elicit and the intent that the bot has determined that the user is trying to fulfill.

The proposedNextState structure is only present when the invocationSource field is DialogCodeHook and when the predicted dialog action is ElicitSlot.

The prediction in proposedNextState holds true only if the Lambda function sets the session state dialogAction to Delegate and if you don't override the dialog's behavior by setting the dialog action or intent. If you override the dialog behavior in sessionState, the next state depends on the settings that you return from your Lambda function.

Response format

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

{ "sessionState": { "activeContexts": [ { "name": "string", "contextAttributes": { "key": "value" }, "timeToLive": { "timeToLiveInSeconds": number, "turnsToLive": number } } ], "sessionAttributes": { "string": "string" }, "runtimeHints": { "slotHints": { "string": { "string": { "runtimeHintValues": [ { "phrase": "string" }, { "phrase": "string" } ] } } } }, "dialogAction": { "slotElicitationStyle": "Default | SpellByLetter | SpellByWord", "slotToElicit": "string", "type": "Close | ConfirmIntent | Delegate | ElicitIntent | ElicitSlot" }, "intent": { "confirmationState": "Confirmed | Denied | None", "name": "string", "slots": { "string": { "value": { "interpretedValue": "string", "originalValue": "string", "resolvedValues": [ "string" ] } }, "string": { "shape": "List", "value": { "originalValue": "string", "interpretedValue": "string", "resolvedValues": [ "string" ] }, "values": [ { "shape": "Scalar", "value": { "originalValue": "string", "interpretedValue": "string", "resolvedValues": [ "string" ] } }, { "shape": "Scalar", "value": { "originalValue": "string", "interpretedValue": "string", "resolvedValues": [ "string" ] } } ] } }, "state": "Failed | Fulfilled | FulfillmentInProgress | InProgress | ReadyForFulfillment | Waiting" } }, "messages": [ { "contentType": "CustomPayload | ImageResponseCard | PlainText | SSML", "content": "string", "imageResponseCard": { "title": "string", "subtitle": "string", "imageUrl": "string", "buttons": [ { "text": "string", "value": "string" } ] } } ], "requestAttributes": { "string": "string" } }

Note the following additional information about the response fields:

  • sessionState – Required. The current state of the conversation with the user. The actual contents of the structure depends on the type of dialog action.

    • dialogAction – Determines the type of action that Amazon Lex V2 should take in response to the Lambda function. The type field is always required. The slotToElicit field is required only when dialogAction.type is ElicitSlot.

    • intent – The name of the intent that Amazon Lex V2 should use. Not required when dialogAction.type is Delegate or ElicitIntent.

      • state – Required. The state can only be ReadyForFulfillment if dialogAction.type is Delegate.

  • messages – Required if dialogAction.type is ElicitIntent. One or more messages that Amazon Lex V2 shows to the customer to perform the next turn of the conversation. If you don't supply messages, Amazon Lex V2 uses the appropriate message defined when the bot was created. For more information, see the Message data type.

    • contentType – The type of message to use.

    • content – If the message type is PlainText, CustomPayload, or SSML, the content field contains the message to send to the user.

    • imageResponseCard – If the message type is ImageResponseCard, contains the definition of the response card to show to the user. For more information, see the ImageResponseCard data type.