Best Practices for Authoring Dialogs in Alexa Conversations
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.
• 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?
Alexa: What date?
Alexa: Are you sure you want the weather for Seattle today?
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
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.
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.
- Design for Natural Speech
- Dialog Act Reference for Alexa Conversations
- Work with Dialog Acts in Alexa Conversations
- Get Started With Alexa Conversations
Was this page helpful?
Last updated: Nov 27, 2023