Tutorial: Annotate a Dialog for Alexa Conversations

---

This tutorial walks you through how to annotate a simple dialog for a weather skill that uses Alexa Conversations. You annotate the following dialog:

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

For a real skill, you typically annotate several dialogs to illustrate the various ways you expect a user to interact with your skill. This tutorial steps you through dialog annotation only; it doesn't include back-end skill code.

• Steps to annotate a dialog for an Alexa Conversations skill
• Prerequisites
• Step 1: Write a dialog
• Step 2: Create a custom slot type for the returned results
• Step 3: Annotate the first user turn
• Step 4: Annotate the user turn that provides information
• Step 5: Annotate the Alexa turn that invokes an API
• Step 6: Annotate the Alexa turn that asks for information
• Step 7: Build the skill model
• Related topics

Steps to annotate a dialog for an Alexa Conversations skill

To annotate a dialog, complete the following steps.

1. Write a dialog.
2. Create a custom slot type for the returned results.
3. Annotate the first user turn.
4. Annotate the user turn that provides information.
5. Annotate the Alexa turn that invokes an API.
6. Annotate the Alexa turn that asks for information.
7. Build the skill model.

Prerequisites

Before you do this tutorial, you must have an Alexa Conversations skill. If you don't have a skill yet, create one in the developer console as follows.

To create an Alexa Conversations skill

1. Log in to the developer console.
2. Click Create Skill.
3. Enter a name for your skill.
4. For Choose a model to add to your skill, click Custom.
5. For Choose a method to host your skill's backend resources, choose Provision your own.
   For this tutorial, it doesn't matter which hosting method you choose because this tutorial doesn't involve any back-end code to host.
6. At the top right, click Create skill.
7. For Choose a template to add to your skill, click Start from Scratch, and then click Choose.
8. Enable the interfaces that are necessary to support Alexa Conversations as follows:
   1. In the left pane, click Interfaces.
   2. In the interface list, enable Alexa Presentation Language.
   3. In the interface list, enable Alexa Conversations, and then select the check box for Use Alexa Conversations as the default dialog manger.
   4. In the header bar, click Save Interfaces.
9. In the left pane, choose Invocation.
10. Change the invocation name, and then at the top, click Save.

Step 1: Write a dialog

The first step is to write a typical conversation that might happen between Alexa and the user during the course of your skill. Here, we enter the weather skill conversation given at the top of this page.

To write a dialog

1. In the left pane, expand Alexa Conversations.
2. Click Dialogs, and then click Add Dialog.
3. For the dialog name, enter dialog0.
4. For the USER: line, enter What's the weather?
5. For the ALEXA: line, enter For what city?
6. Under the dialog, click User says, and then in the USER: line, enter Seattle.
7. Click Alexa says, and then in the ALEXA: line, enter In Seattle, it's 70 degrees.
8. In the header bar, click Save.
   The USER: lines and ALEXA: lines (that is, the turns) have exclamation circles to the right of them, to show that you still must configure these turns. For the user turns, you must configure utterance sets, and for the Alexa turns, you must configure responses. To tie the conversation together, you also must label slot types and define APIs. You do these tasks in subsequent steps.

   

Step 2: Create a custom slot type for the returned results

In this step, you create a custom slot type for the information that the API returns. In this example, the GetWeather API returns a city and a temperature, so Alexa can say, "In Seattle, it's 70 degrees." You therefore must create a custom slot type that contains properties for a city and a temperature, as follows.

To create a custom slot type

1. In the left pane, under Assets, click Slot Types.
2. Click Add Slot Type.
3. Select Create a custom slot type with properties, enter the name returnedWeather, and then click Next.

   

4. Click Add a new property, enter the name city, and then select slot type AMAZON.US_CITY.
5. Repeat the previous step to add a property with the name temperature and slot type AMAZON.NUMBER.

   

6. In the header bar, click Save.

Step 3: Annotate the first user turn

Returning to the dialog, examine the first user turn, and this time, think about what is going on when the user is speaking.

When the user asks, "What's the weather?" the user wants to invoke an API that returns the weather. You therefore define an utterance set, of dialog act Invoke APIs, that groups together the variety of ways that the user might ask Alexa for the weather.

Normally, in user turns you also highlight and assign slot types to any words that you expect to have variable values. This user turn ("What's the weather?") has no words that have variable values, so you only need to create an utterance set.

To annotate the first user turn

1. In the left pane, under Dialogs, click the dialog you created in Step 1: Write a dialog.
2. Click anywhere within the first user turn.
3. On the right, in the User Input panel, select dialog act Invoke APIs.
4. Under Utterance Set, click the box, and then select Create New Utterance Set.
5. Name the utterance set get_weather.
   Because you already selected a dialog act, the dialog act box automatically populates with Invoke APIs. You only need to select the API definition.
6. Under Sample Utterances, click Add Utterance, enter What's the weather?, 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.
7. Repeat the previous step and add sample utterances I want the weather and Give me the weather.
   Make sure to press enter after each entry.

   

8. In the utterance set dialog box, click Save.
9. In the header bar, click Save.

Step 4: Annotate the user turn that provides information

The GetWeather API requires a city, so you must annotate the user turn ("Seattle") that provides the city. The user might name any city in place of "Seattle," so you must label the city with a slot type.

You then define an utterance set of dialog act Inform Args that groups together the variety of ways that the user might give Alexa the city.

To annotate the user turn that provides information

1. In the user turn for "Seattle", highlight Seattle.
2. For Slot Type, select AMAZON.US_CITY.
3. Leave the Variable name at its default value, and then click Add.

   

4. In the header bar, click Save.
5. Back in the dialog, click anywhere within the user turn "Seattle".
6. On the right, in the User Input panel, select dialog act Inform Args.
7. Under Utterance Set, click the box, and then select Create New Utterance Set.
8. Name the utterance set inform_city.
   Because you already selected a dialog act, the dialog act box automatically populates with Inform Args.
9. Under Sample Utterances, click Add Utterance, enter {city}, and then press enter.
   Don't forget to press enter.
10. Repeat the previous step to add sample utterances In {city} and For {city}, making sure to press enter after each one.
11. Scroll down to Slots.
    The city slot is automatically in the slot list because you included it in your sample utterances.
12. For the city slot type, select AMAZON.US_CITY.
13. In the utterance set dialog box, click Save.

    

14. In the header bar, click Save.
15. On the right, in the User Input panel for the "Seattle" user turn, edit the Variable → Slot mapping to amazonUSCITY0 → city.

    

16. In the header bar, click Save.

Step 5: Annotate the Alexa turn that invokes an API

In your dialog, the Alexa turn that invokes an API is "In Seattle, it's 70 degrees." This turn invokes the GetWeather API. You annotate this turn by picking a dialog act and creating a response.

To annotate the Alexa turn that invokes an API

1. In your dialog, click anywhere within the Alexa turn "In Seattle, it's 70 degrees."
2. On the right, in the Alexa Response panel, for the dialog act, select API Success.
3. Under API to Invoke, click Create New API Definition.
4. Name the API GetWeather.
5. Under Arguments, click Add Argument.
6. For the argument name, enter city. For the slot type, select AMAZON.US_CITY.
7. Under Return, select the returnedWeather slot type that you created.

   

8. In the API definition dialog box, click Save.
9. In the header bar, click Save.
   You return to the Alexa Response panel for the "In Seattle, it's 70 degrees." Alexa turn.
10. If you don't see a section for variable-to-argument mappings in the API to Invoke section, click the box where you selected the GetWeather API, and the variable-to-argument mappings should appear.
11. In the API to Invoke section, edit the Variable → Arguments mapping to amazonUSCITY0 → city.
12. Edit the Return Type → Variable mapping to returnedWeather → returnedWeather0.

    

13. Under Response, click Select a Response, and then click Create New Response.
14. For the response name, enter return_weather.
15. Under Alexa Prompts, in "In Seattle, it's 70 degrees," highlight Seattle.
    A slot selection box appears.
16. At the bottom of the slot selection box, for Create a new argument, enter city, and then click Add.
17. Scroll down past Visual Response to the Arguments section.
18. For the city argument, select the AMAZON.US_CITY slot type.

    

19. Click Save.
20. In the right panel, under Response, edit the Variable → Arguments mapping to returnedWeather0.city → city.

    

21. In the header bar, click Save.

Step 6: Annotate the Alexa turn that asks for information

You still need to annotate the Alexa turn "For what city?" By asking this question, Alexa is asking for information that the GetWeather API needs, so the dialog act you assign is Request Args.

To annotate the Alexa turn that asks for information

1. Go back to your dialog and click anywhere within the Alexa turn "For what city?"
2. For the dialog act, select Request Args.
3. For API to Request, select GetWeather.
   API Arguments to Request should automatically populate with city.

   

4. Under Response, click Select a Response, and then click Create New Response.
5. For the response name, enter request_city.
6. Scroll to the bottom of the dialog box and then click Save.

   

7. In the header bar, click Save.

Step 7: 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.

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

• In the header bar, click Build Model.
  The light Alexa Conversations build begins. If the build fails, see Issue: I get errors when I build the model.

If the light build succeeds, the full build begins.

Related topics

• Troubleshoot Your Alexa Conversations Skill
• Get Started With Alexa Conversations
• Steps to Create a Skill with Alexa Conversations

---

---

Last updated: Nov 27, 2023