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.

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.

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.