Dialog Act Reference for Alexa Conversations
• GA:
en-US
, en-AU
, en-CA
, en-IN
, en-GB
, de-DE
, ja-JP
, es-ES
, es-US
• Beta:
it-IT
, fr-CA
, fr-FR
, pt-BR
, es-MX
, ar-SA
, hi-IN
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 types of dialog acts: request acts and response acts. Request acts represent the purpose of user utterances. Response acts represent the purpose of Alexa responses.
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)
Request acts
When you create an utterance set, you associate it with one of the following request acts.
Request Act | Description |
---|---|
The user is affirming the request in the previous turn. |
|
The user is denying the request in the previous turn. |
|
The user is providing arguments that Alexa requested in the previous turn. |
|
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?"
Response acts
When you configure an Alexa response, you associate the response with one of the following response acts.
Response Act | Description |
---|---|
Alexa is notifying the user that the API call was unsuccessful. |
|
Alexa is notifying the user that the API call was successful. |
|
Alexa is confirming all required API arguments and optional API arguments (any number) with the user. |
|
Alexa is confirming arguments (one or many) with the user. |
|
To keep the conversation going, Alexa is offering a dialog path to invoke another API to the user (but not on this turn). |
|
Alexa is offering a dialog path to invoke the same API (but not on this turn) and requesting the specified arguments. |
|
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 AlexaConversationsRequestMore response 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.Response
: The response to render to the user. The response type must contain all the mandatory arguments of theAPI to confirm
.
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.
- Response type properties for additional responses must be a subset of the primary response type. The values/variables mapped to the response type properties depend on the values selected in the primary response.
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 AlexaConversationsRequestMore response 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 theNext API to offer
(required and/or optional). This field is optional. If used, the subsequent user input turn should use dialog act Inform.
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) toAPI to offer
arguments if the names of the response arguments and theAPI 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.
- A dialog can't end with Offer Next API.
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 theAPI 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).
Limitations:
The response you select can't have a type selected.
Related topics
- Work with Dialog Acts in Alexa Conversations
- Steps to Create a Skill with Alexa Conversations
- Get Started With Alexa Conversations
Last updated: Nov 27, 2023