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 (request act and response 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 custom slot types

Create custom slot types for all types that you pass around in your dialog, such as 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: Configure the first user input turn

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

  • Choose a request act. Typically, the first user input turn uses the Invoke APIs request act 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.
  • In the sample utterances, use braces ({}) around variables. You use variables throughout the dialog to map utterance set slots, API definition arguments, and response arguments.

Step 4: Configure the Alexa response turn that requests arguments

Click the next Alexa response turn and configure it by using the Alexa Response panel on the right. Typically, the next Alexa response turn uses the Request Args response act 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 configure your Alexa response, you create an audio response (and optionally, a visual response). When you create your response, you can click the following links to open a new tab to edit your audio or visual response, respectively:

  • Save Model and open APL for Audio editor for advanced updates to [audioResponseName]
  • Use the APL tool to view/edit [visualResponseName]

When you're finished editing, save your changes by clicking the disk in the top right corner. Close the tab to return to the Build page of the developer console.

Step 5: Configure 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 configure this Alexa turn, you do the following:

  • Select a response 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 response act if the Alexa response has more than one purpose.

For examples, see the following sections in Tutorial: Annotate a Dialog for Alexa Conversations:

Step 6: Customize the built-in responses

Alexa Conversations comes with built-in responses such as AlexaConversationsWelcome and AlexaConversationsBye. Customize the built-in responses to make sense for your skill. For example, update the AlexaConversationsWelcome response to provide information about the skill and help the user navigate through the core functionality.

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 Audio Responses, and then find the response you want in the list.