Best Practices for Authoring Dialogs in Alexa Conversations

Note: Sign in to the developer console to build or publish your skill.

Note: Alexa Conversations currently supports the following locales:
• 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

As a best practice, create your Alexa Conversations dialogs, slot types, API definitions, user utterance sets, and responses in the following order. For details on supported dialog act flows, see Work with Dialog Acts in Alexa Conversations.

Important: To avoid data loss as you work in the developer console, keep the following tips in mind:
• Save often. Navigating between tabs doesn't always count as activity to extend your developer console session.
• Be sure that you use only one browser tab to edit your model from the Build page. It's OK to have multiple browser tabs open — for example, one tab for the Build page, one tab for the Code page, and one tab for the Test page — but if you have two Build tabs open and you make changes in one of the tabs, you risk data loss.

Step 1: Create a simple dialog
Step 2: Create a custom slot type
Step 3: Annotate the first user input turn
Step 4: Annotate the Alexa response turn that requests arguments
Step 5: Annotate the Alexa turn that invokes an API
Step 6: Customize the built-in responses
Related topics

Step 1: Create a simple dialog

Create a simple back-and-forth conversation between the user and Alexa, starting with a user turn. This dialog helps Alexa Conversations gather arguments that Alexa can use to invoke an API. Start with a simple conversation. You can expand on this conversation with additional features and complexity later.

All Alexa response turns should ask the user a question, unless it is the final turn of the dialog and you want the session to end or the subsequent turn is an Alexa response turn with a question.

Here, we use the following dialog from an example weather skill as a reference.

User: What's the weather?
Alexa: What city?
User: Seattle.
Alexa: What date?
User: Today.
Alexa: Are you sure you want the weather for Seattle today?
User: Yes.
Alexa: The weather in Seattle for today is 70 degrees.

Step 2: Create a custom slot type

Create a custom slot type for the API return value. Continuing the previous example, the weather skill might have a custom slot type called WeatherResult with properties city, temperature, and date.

Step 3: Annotate the first user input turn

Click the first user input turn and annotate it by using the User Input panel as follows:

Choose a user input dialog act. Typically, the first user input turn uses dialog act Invoke APIs to indicate that the user is on a dialog path to invoke API(s).
Create or choose an utterance set. For each utterance set, you must explicitly specify at least one sample utterance.
Annotate slots in the utterance by highlighting phrases to define slot types and variables. Variables are used throughout the dialog to map utterance set slots, API definition arguments, and response arguments.

Step 4: Annotate the Alexa response turn that requests arguments

Click the next Alexa response turn and annotate it by using the Alexa Response panel on the right. Typically, the next Alexa response turn uses dialog act Request Args to indicate that Alexa is requesting arguments from the user that will later be used to invoke an API. For the weather skill example, the first Alexa turn that requests arguments is "What city?"

As you annotate your Alexa response, you create an audio response (and optionally, visual response). We suggest that you author audio and visual responses as follows:

When you create and edit a new audio response on the Response page (for simple audio responses), make sure to click the gray Save button below Alexa Prompts to save the audio response. Also click the Save button in the modal.
Click Edit Audio Response and Edit Video Response to open the editor in a new tab. When you are finished editing, save your changes by clicking the disk in the top right corner and close the tab to come back to the Response page.

Step 5: Annotate the Alexa turn that invokes an API

When an interaction between Alexa and the skill triggers Alexa Conversations to invoke an API in your skill code, Alexa returns the API results to the user by using an Alexa response. For the weather skill example, the Alexa turn that invokes an API is "The weather in Seattle for today is 70 degrees" because this information is the output of the GetWeather API. To annotate this Alexa turn, you do the following:

Select a dialog act of API Success or API Failure.
Create an API definition that specifies the arguments and return type of the API.
Configure a response for Alexa to say to the user when the API returns.
(Optional) Specify the response conditions to define whether the API succeeded or failed.
(Optional) Choose a second dialog act if the Alexa response has more than one purpose.

To annotate the Alexa turn that returns the results of an API

Log in to the developer console, and then navigate to your Alexa Conversations skill.
In your dialog, click within the Alexa turn that tells the user the results of an API.
For the weather skill example, this turn is "The weather in Seattle for today is 70 degrees"
On the right, in the Alexa Response panel, for the dialog act, select API Success or API Failure.
Under API to Invoke, click Create New API Definition.
Name the API.
For every input argument to the API, click Add Argument, name the argument, and then select a slot type.
For example, the input argument to the GetWeather API is called city and has a slot type of AMAZON.US_CITY.
Under Return, select the custom slot type that you created in Step 2: Create a custom slot type.
In the API definition dialog box, click Save.
In the header bar, click Save.
You return to the Alexa Response panel for the Alexa turn.
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 API, and the variable-to-argument mappings should appear.
In the API to Invoke section, select the Variable → Arguments mappings and the Return Type → Variable mappings
Under Response, click Select a Response, and then click Create New Response.
Enter a response name.
Under Alexa Prompts, highlight a variable in the response. A slot selection box appears.
At the bottom of the slot selection box, for Create a new argument, enter your argument name, and then click Add.
Repeat the previous steps to add additional arguments as necessary.
Scroll down past Visual Response to the Arguments section.
Select the slot types for your arguments.
Click Save.
In the right panel, under Response, select the Variable → Arguments mappings.
(Optional) In the Condition field, specify response conditions that define whether the API succeeded or failed.
You define conditions by using APL Data-Binding Syntax.
(Optional) If this Alexa turn has more than one purpose, click Add another Dialog Act at the bottom of the Alexa Response panel. For example, in a weather skill, if the utterance is "The weather in Seattle for today is 70 degrees. Would you like the hour-by-hour forecast?" you would add the dialog act Offer Next API with a new API that provides hour-by-hour forecast information and pass response arguments for the city and date.
In the header bar, click Save.

Step 6: Customize the built-in responses

Alexa Conversations comes with built-in responses such as welcome and provide_help. Customize the built-in responses to make sense for your skill. For example, update the welcome response to provide information about the skill and help the user navigate through the core functionality. Update the provide_help response to provide information on how to use the skill, and so on.

For a list of built-in responses and when they're triggered, see Built-in Response Reference for Alexa Conversations.

To access all the responses (both built-in and custom), go to the left pane, expand Alexa Conversations, expand Responses, and then find the response you want in the list.

Was this page helpful?

Provide feedback

Last updated: Nov 27, 2023