Tutorial: Annotate a Dialog for Alexa Conversations

---

This tutorial walks you through how to create and configure Alexa Conversations elements for a simple weather skill that uses Alexa Conversations. You use 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 use several dialogs to illustrate the various ways you expect a user to interact with your skill. This tutorial steps you through the process of creating and configuring Alexa Conversations elements; 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 custom slot types
• Step 3: Create an API definition
• Step 4: Edit utterance sets
• Step 5: Edit audio responses
• Step 6: Tie together the elements of the dialog
• 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 custom slot types.
3. Create an API definition.
4. Edit utterance sets.
5. Edit audio responses.
6. Tie together the elements of the dialog.
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.
   The skill takes a few minutes to set up.
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, expand Invocations, and then click Skill Invocation Name.
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 flow of your skill. Here, you enter a dialog that corresponds to the weather skill conversation at the top of this page.

To write a dialog

1. In the left pane, expand Alexa Conversations.
2. Click Dialogs.
3. At the bottom of the main window, click Create New Alexa Conversations Model.
4. In the left pane, expand Alexa Conversations again, and then click Dialogs.
5. Click Add Dialog.
6. For the dialog name, enter dialog0.
7. For the USER: line, enter What's the weather?
8. For the ALEXA: line, enter For what city?
9. Under the dialog, click User says, and then in the USER: line, enter {city}.
   The braces around city indicate that city is variable.
10. Click Alexa says, and then in the ALEXA: line, enter In {city}, it's {temperature} degrees.
11. 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.

    

If you browse through the items under Alexa Conversations in the left panel, you might notice that when you created the dialog, Alexa Conversations automatically created some assets for you. Alexa Conversations created two utterance sets (utteranceSet0 and utteranceSet1) because there are two user lines in the dialog.

Alexa Conversations also created two audio responses (audioResponse0 and audioResponse1), because there are two Alexa responses in the dialog. In subsequent steps, you go into these assets, make the names more descriptive, and fill out the remaining settings that each asset needs.

Step 2: Create custom slot types

You must create a custom slot type for every type of variable you use in a dialog. For this dialog, you need to create three custom slot types:

• a type for the city
• a type for the weather, which contains a city and temperature
• a type that you can specifically use to pass the weather result to the audio response of a successful call to the GetWeather API

Create these types by using the following steps.

To create a custom slot type for the city

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 CityType, and then click Next.
4. Click Add a new property, enter the name city, and then select slot type AMAZON.US_CITY.
5. In the header bar, click Save.

   

To create a custom slot type for the weather

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 WeatherType, 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.

   

To create a custom slot type to pass the weather result to the audio response

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 WeatherTypeForSuccess, and then click Next.
4. Click Add a new property, enter the name returnedWeather, and then select slot type WeatherType.
5. In the header bar, click Save.

   

Step 3: Create an API definition

You must create API definitions for all APIs that Alexa Conversations can call during the conversation between the user and Alexa.

In this example, the skill has one API, which gets the weather. The API, which we call GetWeather, takes a city and returns the weather, which consists of a city and a temperature.

To create an API definition

1. In the left pane, under Alexa Conversations, click API Definitions.
2. Click Add API Definition.
3. Replace the default name with the name GetWeather.
4. Under Arguments, click Add Argument.
5. For the argument name, enter city. For the slot type, select AMAZON.US_CITY.
6. Under Return, select the WeatherType slot type that you created.
7. In the header bar, click Save.

   

Step 4: Edit utterance sets

As previously mentioned, when you created your dialog in Step 1, Alexa Conversations automatically created a few utterance sets for you. You can see these utterance sets when you go to the left panel, and, under Alexa Conversations, expand Utterance Sets.

One utterance set corresponds to the user turn What's the weather?, and represents different ways the user can ask for the weather. The other utterance set, for the user turn {city}, represents different ways the user can tell Alexa the city, when Alexa specifically requests this information.

The utterance sets that Alexa Conversations automatically creates have generic names and are missing some settings. In this step, you update the names and fill in the missing information.

To edit the user turn that asks for the weather

1. In the left pane, expand Utterance Sets, and then click utteranceSet1.
2. In the main window, rename the utterance set to InvokeGetWeather.
3. Under Request Act, select Invoke APIs.
4. Under Sample Utterances, click Add Utterance, enter I want the weather, and then press enter.
5. Repeat the previous step and add sample utterance Give me the weather, but don't press enter this time.
   Ignore the Type Configuration section. There are no variables in these utterances.
6. In the header bar, click Save.

   

To edit the user turn that provides the city

1. In the left pane, under Utterance Sets, click utteranceSet0.
2. In the main window, rename the utterance set to InformCity.
3. Under Request Act, select Inform Args.
4. Under Type Configuration, select the CityType slot type that you created.
5. In the header bar, click Save.

   

Step 5: Edit audio responses

As previously mentioned, when you created your dialog in Step 1, Alexa Conversations automatically created a few audio responses for you. You can see these audio responses when you go to the left panel, and, under Alexa Conversations, expand Audio Responses.

One audio response corresponds to the What city? Alexa turn, and represents different ways Alexa can ask for the city. The other audio response, for the Alexa turn In {city}, it's {temperature} degrees, represents different ways Alexa can report the outcome of the GetWeather API call to the user.

The audio responses that Alexa Conversations automatically creates have generic names and are missing some settings. In this step, you update the names and fill in the missing information.

To edit the audio response that asks for the city

1. In the left pane, expand AudioResponses, and then click audioResponse0.
2. In the main window, rename the audio response to RequestCity.
3. Under Alexa Prompts, click Add prompt, and then enter In what city?.
   Ignore the Type Configuration section. There are no variables in these Alexa prompts.
4. In the header bar, click Save.

   

To edit the audio response that returns the weather

1. In the left pane, under AudioResponses, click audioResponse1.
2. In the main window, rename the audio response to ReturnWeatherSuccess.
3. Under Type Configuration, select the WeatherTypeForSuccess slot type that you created.
4. Scroll back up to the Alexa Prompts section, and double-click {city}.
5. From the drop-down, select returnedWeather.city.
6. Double-click {temperature}.
7. From the drop-down, select returnedWeather.temperature.
8. Under Properties, if a temperature property appeared, delete this property.
   The only property should be returnedWeather.
9. In the header bar, click Save.

   

Step 6: Tie together the elements of the dialog

Now that you've set up your slot types, API definitions, utterance sets, and Alexa response, you need to go back to your dialog and tie these elements together.

The first user turn, What's the weather?, is already configured. You need to configure the other three turns.

To configure the Alexa turn that asks for the city

1. In the left pane, expand Dialogs, and then click the dialog you created in Step 1: Write a dialog.
2. In the dialog, click anywhere within the Alexa turn For what city?.
3. On the right, in the Alexa Response panel, under Response Act, select Request Args.
4. Under API to Request, click the box, and then select GetWeather.
   API Arguments to Request automatically populates with city.
5. In the header bar, click Save.

   

To configure the user turn that gives the city

1. In the dialog, click anywhere within the user turn {city}.
2. On the right, in the User Input panel, under Output Variable, enter city0.
3. In the header bar, click Save.

   

To configure the Alexa turn that returns the weather

1. In the dialog, click anywhere within the last Alexa turn, which corresponds to In {city}, it's {temperature} degrees.
2. On the right, in the Alexa Response panel, for the response act, select API Success.
3. Under API to Invoke, click the box, and then select GetWeather.
   A Variables → Arguments mapping appears under GetWeather.
4. Set the variable-to-argument mapping to the following:
   city0.city → city
5. At the bottom of the Response section, expand Properties of WeatherTypeForSuccess.
6. Configure the variable mapping to the following:
   weatherType0 → returnedWeather
7. In the header bar, click Save.

   

Step 7: Build the skill model

Your next step is to build the skill model.

To build the skill model

• In the header bar, click Build Model.
  The light Alexa Conversations build begins. If the build fails, click back through all of the lines of your dialog, and ensure that you don't see any red errors. Also, 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