Write Dialogs for Alexa Conversations

When you create an Alexa Conversations skill, your first step is to write one or more sample conversations between Alexa and the user. These sample conversations are called dialogs. Dialogs are examples of conversations that you expect to occur between Alexa and the user throughout the course of your skill.

You write the dialogs in simple text and then "mark up" the dialogs to show which parts of the dialogs represent user utterance sets, Alexa responses, and API calls. The marked-up dialogs are called annotated dialogs.

You can write and annotate your dialogs entirely in the developer console.

Get Started

To get started with Alexa Conversations, you can step through a pet match skill-building tutorial, download the code for a pizza-ordering reference skill, or use an Alexa-hosted sample skill template that includes an Alexa Conversations skill configuration and back-end skill code.

Write a dialog

You write a dialog in the developer console by entering a user utterance and an Alexa utterance, turn by turn. The following example shows a dialog for a pizza-ordering skill.

User: I'd like to order a pizza for delivery.
Alexa: Ok. What size pizza?
User: Large.
Alexa: What toppings?
User: Green peppers and olives.
Alexa: Would you like to order anything else?
User: No.
Alexa: Ok. Your pizza will arrive in about 25 minutes.

When you write the utterances, the punctuation (including "," and ".") can affect how Alexa Conversations interprets the sentences. Use punctuation that is grammatically correct in English.

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.

Create as many dialogs as you need to cover basic conversations for your skill. For a pizza-ordering skill, other dialogs might be a dialog in which the skill offers the user the daily specials, the user orders multiple pizzas, and so on.

To write a dialog

  1. Log in to the developer console, and then navigate to your Alexa Conversations skill.
  2. In the left pane, expand Alexa Conversations, and then click Dialogs.
    If you don't see Alexa Conversations in the left pane, your skill isn't configured to support the required interfaces. To add the required interfaces, see Start from a blank skill template.
  3. Click Add Dialog.
  4. Enter a name for the dialog.
  5. Click the USER: line, and then enter what a user might say.
    For example, for the pizza-delivery skill, you might enter I'd like to order a pizza for delivery.
  6. Click the ALEXA: line, and then enter how Alexa might respond.
    For example, for the pizza-delivery skill, you might enter Ok. What size pizza?
  7. Add additional user and Alexa utterances by clicking User says and Alexa says, respectively.
    You must follow every user utterance with one Alexa utterance.
  8. In the header bar, click Save.
  9. Annotate the dialog by doing the following in the order recommended by Best Practices for Authoring Dialogs in Alexa Conversations:
    1. Select Slot types – In the user lines, highlight words that represent variables in the spoken utterances. You assign each of these variables a slot type, which determines how Alexa handles the data. For details about slot types, see Use Slot Types in Alexa Conversations.
    2. Create API definitions – When you create an utterance set that has a dialog act of type Invoke APIs, you must associate the user utterance set with the API that the user utterance triggers. To specify the input arguments and return type of the API, you create an API definition. For details about API definitions, see Define APIs for Alexa Conversations.
    3. Annotate user input – Click the user lines, and then, in the user input panel that appears on the right, select an utterance set to add the utterance to, or create a new utterance set. For details about utterance sets, see Add Utterance Sets for Alexa Conversations.
    4. Annotate responses – Click the Alexa lines, and then, in the Alexa response panel that appears on the right, select a dialog act that represents the purpose of the response, associate an API and arguments (if applicable), and then select or create a response. Responses include, at a minimum, an audio prompt that Alexa says to the user. For details about creating responses, see Define Responses from Alexa for Alexa Conversations.
  10. Repeat steps 3 through 9 for each dialog.

Clone a dialog

To introduce a slightly different variation of an existing dialog, you can clone a dialog. A cloned dialog does the following:

  • copies the same user and Alexa utterances
  • references the same Alexa Conversations components (slots, utterance sets, responses and API definitions)
  • copies the dialog annotations (for example, API Arguments to Request)

To clone a dialog

  1. Log in to the developer console, and then navigate to your Alexa Conversations skill.
  2. In the left pane, expand Alexa Conversations, and then click Dialogs.
  3. For the dialog you want to clone, under ACTIONS, click Clone.
  4. Enter a name or accept the default clone name, and then click Save.
  5. In the Dialogs list, find the clone, click Edit, and then make the desired modifications.
Was this page helpful?

Last updated: Nov 27, 2023