Dialog Act Reference for Alexa Conversations

Dialog acts are tags that help Alexa Conversations identify the purpose of user utterances and Alexa responses. Alexa Conversations uses dialog acts to determine the flow of dialogs and to automatically expand dialogs to generate training data with different variations and flows.

There are two sets of dialog acts: user input dialog acts and Alexa response dialog acts. User input dialog acts represent the purpose of user input. Alexa response dialog acts represent the purpose of an Alexa response.

We use the following dialog from an example weather skill as a reference.

User: What's the weather? (Dialog act: Invoke APIs)
Alexa: What city? (Dialog act: Request Args)
User: Seattle. (Dialog act: Inform Args)
Alexa: What date? (Dialog act: Request Args)
User: Today. (Dialog act: Inform Args)
Alexa: Are you sure you want the weather for Seattle today? (Dialog act: Confirm API)
User: Yes. (Dialog act: Affirm)
Alexa: The weather in Seattle for today is 70 degrees. (Dialog act: API Success)

User input dialog acts

When you create an utterance set, you associate it with one of the following dialog acts.

Dialog Act Description

Affirm

The user is affirming the request in the previous turn.

Deny

The user is denying the request in the previous turn.

Inform Args

The user is providing arguments that Alexa requested in the previous turn.

Invoke APIs

The user is on a dialog path to invoking API(s).

Affirm

Indicates the user is affirming the request in the previous Alexa response turn.

There are three general use cases for this dialog act:

  • The user turn is after an Alexa response turn with dialog act Confirm Args.
  • The user turn is after an Alexa response turn with dialog act Confirm API.
  • The user turn is after an Alexa response turn with dialog act Offer Next API.

Examples: "Yes," "Correct."

Limitations: Although Alexa Conversations requires this dialog act after an Alexa response turn with dialog act Confirm Args, Alexa Conversations doesn't use the user input turn (annotated utterance and utterance set). Instead, Alexa Conversations uses a predefined set of utterances such as "Yes" and "Correct."

Deny

Indicates the user is denying the request in the previous Alexa response turn. Creating a dialog with this dialog act is not required, because Alexa Conversations automatically supports negative use cases on your behalf if you don't explicitly provide them.

There are three general use cases for this dialog act:

  • The user turn is after an Alexa response turn with dialog act Confirm Args.
  • The user turn is after an Alexa response turn with dialog act Confirm API.
  • The user turn is after an Alexa response turn with dialog act Offer Next API.

Examples: "No," "Incorrect."

Limitations: Although Alexa Conversations requires this dialog act after an Alexa response turn with dialog act Confirm Args, Alexa Conversations doesn't use the user input turn (annotated utterance and utterance set). Instead, Alexa Conversations uses a predefined set of utterances such as "No" and "Incorrect."

Inform Args

Indicates the user is informing Alexa the value of arguments by using slots that Alexa will eventually use to invoke APIs, but not on this turn. You can also use this dialog act to indicate the user is affirming and informing values (for example, if the previous Alexa response turn is Offer API with requesting arguments). The user input turn (annotated utterance and utterance set) must have at least one slot.

There are two general use cases for this dialog act:

  • The user turn is between a user input turn with dialog act Invoke APIs and an Alexa response turn with dialog act API Success or API Failure, which uses at least one argument that is being informed.
  • The user turn is between an Alexa response turn with dialog act Offer Next API and an Alexa response turn with dialog act API Success or API Failure, which uses at least one argument that is being informed.

Examples: "{city}," "In {city}," "For {city}."

Limitations: You can't use this dialog act to request custom slot types with properties. You can only use it to request custom slot types with values and built-in slot types.

Invoke APIs

Indicates the user is expressing an intent to eventually invoke APIs (but not on this turn). There are two general use cases for this dialog act:

  • The turn is the very first turn of a dialog, which is a user turn.
  • The user turn is after an Alexa response turn with dialog act: API Success or API Failure.

Examples: "What's the weather?", "Can you tell me the weather?"

Alexa response dialog acts

When you configure an Alexa response, you associate the response with one of the following dialog acts.

Dialog Act Description

API Failure

Alexa is notifying the user that the API call was unsuccessful.

API Success

Alexa is notifying the user that the API call was successful.

Confirm API

Alexa is confirming all required API arguments and optional API arguments (any number) with the user.

Confirm Args

Alexa is confirming arguments (one or many) with the user.

Offer Next API

To keep the conversation going, Alexa is offering a dialog path to invoke another API to the user (but not on this turn).

Request Alt

Alexa is offering a dialog path to invoke the same API (but not on this turn) and requesting the specified arguments.

Request Args

Alexa is requesting arguments (one or many) from the user.

API Failure

Indicates Alexa is notifying the user that the API call was unsuccessful.

With API Failure, the API arguments collected so far are not carried forward. This is in contrast to API Success, in which the API arguments collected so far are carried forward.

Example: "Weather data for {city} is not available."

Required fields:

  • API to Invoke: The API to invoke before rendering a response. You can daisy-chain up to two APIs to invoke.
  • Condition: An optional Boolean condition, written in APL data-binding syntax, in which subsequent dialog turns are considered by the simulator. This condition, which doesn't impact rendering the response, can include variables associated with the API return. Each API Success/Failure condition for a given response must be exclusive and together must cover all cases.
  • Response: The response to render to the user.

Second dialog act: You can daisy-chain this dialog act with a second dialog act (Offer Next API or Request Alt).

API Success

Indicates Alexa is notifying the user that the API call was successful.

With API Success, the API arguments collected so far are carried forward. This is in contrast to API Failure, in which the API arguments collected so far are not carried forward.

Example: "The weather in {response.city} for {response.date} is {response.temperature} degrees."

Required fields:

  • API to Invoke: The API to invoke before rendering a response. You can daisy-chain up to two APIs to invoke.
  • Condition: An optional Boolean condition, written in APL data-binding syntax, in which subsequent dialog turns are considered by the simulator. This condition, which doesn't impact rendering the response, can include variables associated with the API return. Each API Success/Failure condition for a given response must be exclusive and together must cover all cases.
  • Response: The response to render to the user.

Second dialog act: You can daisy-chain this dialog act with a second dialog act (Offer Next API or Request Alt).

Confirm API

Indicates Alexa is confirming with the user all required API argument(s) and optional API argument(s) (any number) that belong to an API definition. These arguments are used to invoke an API (but not on this turn) if the user affirms this confirmation. To use this feature, each dialog that invokes a specific API must precede the API Success / API Failure dialog act with turns that confirm the API arguments.

If, on the subsequent user input turn, the user affirms, the dialog will continue. If, on the subsequent user input turn, the user denies, the dialog will exit and the built-in response reqmore will be rendered to keep the conversation going.

Creating a dialog with the Confirm API / Deny path is not required, because Alexa Conversations automatically supports such negative use cases on your behalf if you don't explicitly provide them.

Example: "Are you sure you want the weather for {city} {date}?"

Additional required fields:

  • API to confirm: An API definition with arguments to confirm with the user.
  • API arguments to confirm: Argument(s) to confirm with the user. The arguments belong to the API to confirm, which includes all required arguments and any number of optional arguments.
  • Response: The response to render to the user.

Additional responses: These responses are also associated with the same dialog act and API to confirm. They are automatically populated with permutations of optional arguments and associated responses that have already been created.

Limitations:

  • The Confirm API / Deny path carries forward denied arguments as if they were affirmed.
  • You can't use this dialog act to confirm arguments that are slot types with properties.

Confirm Args

Indicates Alexa is confirming with the user API arguments (one or many) that belong to any API definition. These arguments are eventually used to invoke an API (but not on this turn). To use this feature, each dialog that requests a specific argument must follow the Request Args dialog act with a turn that confirms the argument.

If, on the subsequent user input turn, the user affirms, the dialog will progress. If, on the subsequent user input turn, the user denies, Alexa will then Request Args again for the same set of arguments. Creating a dialog with the Confirm Args / Deny path is not required, because Alexa Conversations automatically supports negative use cases on your behalf if you don't explicitly provide them.

This confirmation is automatically applied across all dialogs and APIs that have the same argument name(s) provided in the API arguments to confirm field.

Example: "Can you confirm the city is {city}?"

Fields:

  • API arguments to confirm: Argument(s) to confirm with the user. The arguments belong to any API definition (required and/or optional). At least one argument is required.
  • Response: The response to render to the user.

Additional responses: These responses are also associated with the same dialog act and API to request. They are automatically populated with permutations of arguments and associated responses that have already been created. For each set of arguments being confirmed, a corresponding Request Args turn with the same set of arguments is required (to support the Confirm Args / Deny path).

Limitations:

  • You can't use this dialog act to confirm arguments that are list type or slot types with properties.

Offer Next API

Indicates Alexa is offering a dialog path to invoke another API (but not on this turn) to the user to keep the conversation going. This dialog act is only valid if the previous turn is an Alexa response turn with dialog act API Success or API Failure or if this turn is daisy-chained with dialog act API Success or API Failure.

If, on the subsequent user input turn, the user affirms, the dialog will continue on a path to the Offer Next API. If, on the subsequent user input turn, the user denies, the dialog will exit and the built-in response reqmore will be rendered to keep the conversation going.

Creating a dialog with the Offer Next API / Deny path is not required, because Alexa Conversations automatically supports negative use cases on your behalf if you don't explicitly provide them.

Example: (Standalone. The previous turn was dialog act API Success): "Would you like an hour by hour forecast for {city} {date}?"

Example: (Daisy-chained with dialog act API Success): "The weather in {response.city} for {response.date} is {response.temperature} degrees. Would you like the hour by hour forecast?"

Fields:

  • Next API to offer: The dialog path to API definition to offer to the user.
  • Next API arguments to request: Argument(s) to request from the user that belong to the Next API to offer (required and/or optional). This field is optional. If used, the subsequent user input turn should use dialog act Inform.
  • Response arguments to pass: The response argument(s) to pass to the Next API to offer.

Limitations:

  • If this dialog act is used as a stand-alone dialog act, Next API arguments to request is not functional. Next API arguments to request works if this dialog act is daisy chained.
  • The Offer Next API / Deny path carries forward denied arguments as if they were affirmed.
  • You can't pass variables or arguments that are slot types with properties to API to offer arguments.
  • You can't pass variables to API to offer arguments and you can only pass response argument(s) to API to offer arguments if the names of the response arguments and the API to offer arguments are the same.
  • If this is a secondary dialog act, complex values are supported. The value can be any response argument and complex values are supported.

Request Alt

Indicates Alexa is offering a dialog path to invoke the same API (but not on this turn) and requesting the specified arguments. This dialog act is only valid if this turn is daisy-chained with dialog act API Failure.

Example: (Daisy chained with dialog act API Failure) "I'm sorry, that date is in the past. Would you like to know the weather for a different date?"

Fields:
Arguments to request: Arguments to request.

Request Args

Indicates Alexa is asking the user for arguments (one or many) that belong to an API definition. Alexa will eventually use these arguments to invoke an API (but not on this turn). This dialog act is tied to the API specified by the API to request field and is not used for other APIs that have the same argument names.

Examples: "Which city?", "What city and what date?"

Fields:

  • API to request: An API definition with arguments to request from the user.
  • API arguments to Request: Argument(s) to request from the user that belong to the API to request (required and/or optional). At least one argument is required.
  • Response: The response to render to the user.

Additional responses: These responses are also associated with the same dialog act and API to request. They are automatically populated with permutations of arguments and associated responses that have already been created. This turn must include responses for each individual required argument (to support features such as user driven error correction).

Was this page helpful?

Last updated: Nov 27, 2023