Tutorial: Confirm API Arguments for Alexa Conversations

In your Alexa Conversations skill, you can use the Confirm API dialog act to have Alexa ask the user to confirm the arguments of an API. If the user denies the arguments, Alexa requests the arguments again. For example, in a weather skill, Alexa might ask the user, "You want the weather for {city}, right?"

This tutorial walks you through how to add argument confirmation to the dialog from Tutorial: Annotate a Dialog. The dialog from that tutorial is as follows.

User: What's the weather?
Alexa: For what city?
User: Seattle.
Alexa: In Seattle, it's 70 degrees.

In this tutorial, you expand the dialog to confirm the city argument as follows.

User: What's the weather?
Alexa: For what city?
User: Seattle.
Alexa: You want the weather for Seattle, right?
User: Right.
Alexa: In Seattle, it's 70 degrees.

Steps to add argument confirmation to an Alexa Conversations skill

Complete the following steps to add argument confirmation to a skill:

  1. Add the dialog turns for argument confirmation.
  2. Annotate the Alexa turn that asks for confirmation.
  3. Annotate the user turn that provides confirmation.
  4. Build the skill model.

Prerequisites

Before you do this tutorial, you must complete Tutorial: Annotate a Dialog.

Step 1: Add the dialog turns for argument confirmation

The first step is to add an Alexa turn that asks the user to confirm the argument, and add a user response that confirms it.

To add the dialog turns for argument confirmation

  1. In the developer console, navigate to the dialog you created in Tutorial: Annotate a Dialog.
  2. Under the dialog, click Alexa says, and then enter You want the weather for Seattle, right?
    The error message about out-of-order Alexa and user turns will disappear after you reposition them.
  3. Click and drag the left side of the Alexa turn to reposition it under the "Seattle" user turn.
  4. Click User says, and then enter Right.
  5. Click and drag the left side of the user turn to reposition it under the "You want the weather for Seattle, right?" Alexa turn.
  6. In the header bar, click Save.
    Weather skill dialog
    Weather skill dialog with an Alexa confirmation turn and a user affirmation turn

Step 2: Annotate the Alexa turn that asks for confirmation

To confirm the argument, you annotate the Alexa turn, "You want the weather for Seattle, right?" with the dialog act Confirm API.

You use this dialog act because you are confirming arguments for a specific API (GetWeather). If you want to confirm API arguments that belong to any API, you use Confirm Args.

To annotate the Alexa turn that asks for information

  1. In the dialog, click anywhere within the Alexa turn "You want the weather for Seattle, right?"
    An Alexa Response panel appears on the right.
  2. For the dialog act, select Confirm API.
  3. For API to Confirm, select GetWeather.
    API Arguments to Confirm automatically populates with city.
  4. Under Response, click Select a Response, and then click Create New Response.
  5. For the response name, enter confirm_city.
  6. Under Alexa Prompts, in "You want the weather for Seattle, right?" highlight Seattle.
    A slot selection box appears.
  7. At the bottom of the slot selection box, for Create a new argument, enter city, and then click Add.
  8. Scroll down past Visual Response to the Arguments section.
  9. For the city argument, select the AMAZON.US_CITY slot type.
  10. Click Save.
    Weather skill dialog
    Alexa response configuration
  11. In the right panel, under Response, edit the VariableArguments mapping to amazonUSCITY0city.
  12. In the header bar, click Save.
    Weather skill dialog
    Alexa turn configuration

Step 3: Annotate the user turn that provides confirmation

For the user turn, you then define an utterance set of dialog act Affirm that groups together the variety of ways that the user might affirm the argument.

To annotate the user turn that provides confirmation

  1. Click anywhere within the user turn "Right".
    A User Input panel appears on the right.
  2. In the User Input panel, select dialog act Affirm.
  3. Under Utterance Set, click the box and then select Create New Utterance Set.
    The utterance set configuration box appears.
  4. Name the utterance set affirm_city.
    Because you already selected a dialog act, the dialog act box automatically populates with Affirm.
  5. Under Sample Utterances, click Add Utterance, enter Right, and then press enter.
    You must do this step even though the utterance is in a grey box; the grey box is just for reference.
  6. Repeat the previous step and add sample utterances Yes and Yup.
    Make sure to press enter after each entry.
  7. Click Save.
  8. In the header bar, click Save.
    Weather skill dialog
    Utterance set configuration

Step 4: Build the skill model

If you look at your dialog, you should see a check mark next to each of the turns, indicating that the turn is fully configured.

Weather skill dialog
Fully configured dialog

If you see an exclamation mark instead of a check mark, then you missed something in the previous steps, and the skill model won't build. You can either try to find the missing configuration or you can build the skill model and look at the error message to give you more information.

To build the skill model

If the light build succeeds, the full build will begin.