Work with Dialog Acts in Alexa Conversations

Dialog acts describe how the user and Alexa interact to accomplish the task of invoking APIs to achieve a specific goal in a sample conversation. The following sections describe supported flows of dialog acts within Alexa Conversations.

For a way to author your dialog to follow these guidelines, see Best Practices for Authoring Dialogs in Alexa Conversations. For details about all dialog acts, see Dialog Act Reference for Alexa Conversations.

How to work with dialog acts at different stages

The use of dialog acts is best described as a loop with five major stages and a goal of invoking API(s). At the beginning of the loop, assume that the dialog is in one of the following places:

  • The first turn of a dialog (that is, the user input turn)
  • After an Alexa response turn with dialog act API Success or API Failure
  • After an Alexa response turn with the built-in reqmore response template

From there, the stages are as follows:

  1. The user or Alexa triggers the intention to invoke an API.
  2. Alexa asks questions.
  3. The user responds to Alexa.
  4. Stages 2 and 3 repeat as needed.
  5. Alexa invokes API(s).

Stage 1: The user or Alexa triggers the intention to invoke an API

Because dialog authoring in Alexa Conversations is API-centric, you generally start by triggering the intention to invoke an API. As shown in the following table, you can accomplish this in one of the two ways.

If this... ...then do this

The user input and sample utterances associated with the utterance set express an intention by the user to eventually invoke an API.

Use the user input dialog act Invoke API(s) and then go to Stage 2.

The Alexa response expresses an offer to the user to eventually invoke another API with certain arguments pre-filled.

Use the Alexa response dialog act Offer Next API and then go to Stage 3.

Stage 2: Alexa asks questions

The following table shows the priority of the dialog acts you should follow in this stage to ensure a consistent user experience.

If this... ...then do this

On the last user input turn, the user denied the previous Alexa response dialog act Confirm API Arguments or Offer Next API.

Set a response with the built-in reqmore response template and then go to Stage 3.

The user denied a previous Alexa response's dialog act Confirm Arguments, and Alexa hasn't requested all the arguments to confirm yet. (There might be multiple requests to cover the entire set of arguments to confirm.)

Go to Stage 3.

Alexa already has sufficient information to invoke the API with the required arguments, and you want to make sure that all the required (and any number of optional) arguments are confirmed.

Use the Alexa response dialog act Confirm API and then go to Stage 3.

For example, "I'm saving your trip from Seattle to Portland on April 21st. Is that OK?" This response confirms the entire PlanMyTrip API.

Alexa doesn't have sufficient information to invoke the API with the required arguments, but you want to confirm a set of these arguments whenever the user provides them (and has an Alexa response dialog act Request Args to fill the same set of arguments).

Use the Alexa response dialog act Confirm Args and then go to Stage 3.

For example, "You said you're leaving from Seattle, right?" This confirms the fromCity argument.

Alexa doesn't meet any of the previous criteria. That is, Alexa doesn't have enough information to call an API with the desired arguments and no user-informed value to fill for any argument.

Use the Alexa response dialog act Request Args to ask the user for a slot value to fill an API argument and then go to Stage 3. The user answers with a slot value or a full utterance that includes the slot value.

For example, "What city are you leaving from?" (This response requests a value for a fromCity argument.)

None of these conditions are met. Alexa is ready to call an API with all desired arguments and nothing needs to be confirmed.

Go to Stage 5.

Stage 3: The user responds to Alexa

In this stage, the user responds to Alexa.

If this... ...then do this

The previous Alexa response had dialog act Offer Next API (with no arguments to request), Confirm API, or Confirm Args, and the user wants to affirm the arguments and/or the API.

Use the user input dialog act Affirm and then go to Stage 4.

The previous Alexa response had dialog act Offer Next API (with no arguments to request), Confirm API, or Confirm Args, and the user wants to deny the arguments and/or the API.

Use the user input dialog act Deny and then go to Stage 4.

The previous Alexa response had dialog act Offer Next API (with arguments to request) and the user wants to provide arguments for the next API and then go to Stage 4.

Use the user input dialog act Inform and then go to Stage 4.

The previous Alexa response had dialog act Offer Next API (with arguments to request) and the user wants to deny the arguments and/or the API.

Use the user input dialog act Deny and then go to Stage 4.

The previous Alexa response had dialog act Request API and the user wants to provide arguments.

Use the user input dialog act Inform and then go to Stage 4.

The user is responding to the built-in reqmore response template.

Go to Stage 1 or end the dialog.

Stage 4: Stages 2 and 3 repeat as needed

Repeat stages 2 and 3 until you are ready to invoke API(s).

Stage 5: Alexa invokes API(s)

In this stage, Alexa invokes API(s) and renders the API Success or API Failure response for the previous API.

If this... ...then do this

Alexa is informing the user of the result of an API.

For example, "You can't plan a trip for a date that has passed, so please tell me a date in the future." This prompt comes after the user provided a date before today for the travelDate slot.

Use the Alexa response dialog act API Success or API Failure.

You checked the slot value against pre-defined rules and prompt the user if it fails. The user can then respond with a corrected value.

For example, "You can't plan a trip for a date that has passed, so please tell me a date in the future." This prompt comes after the user provided a date before today for the travelDate slot.

Use the Alexa response dialog act API Failure followed by Request Alt, and then go to Stage 3.

Repeat stages 1 through 5 until all tasks in the dialog are accomplished.

Was this page helpful?

Last updated: Nov 27, 2023