Dialog Interface Reference


The Dialog interface provides directives for managing a multi-turn conversation between your skill and the user. You can use the directives to ask the user for the information you need to fulfill their request.

Dialog directive requirements (dialog model)

To use most of the Dialog directives, your skill must include a dialog model. The dialog model is a structure that identifies:

  • The slots that must be filled with valid values in order to fulfill the intent. These are considered required slots.
  • The prompts Alexa speaks to ask for required slot values and the utterances users can say in reply.
  • Whether any of the required slots must be also confirmed by the user before continuing.
  • Whether the entire intent must be confirmed by the user before continuing.
  • The prompts Alexa speaks to ask for slot and intent confirmations.
  • Any slot validation rules that the slot value provided by the user must pass to be considered valid. These rules can be used with both required and non-required slots.
  • The prompts Alexa speaks to ask for a corrected value when the user's response fails slot validation.

How the dialog model is used when a user interacts with your skill depends on how you choose to manage the conversation.

You can use the developer console to create the create a dialog model. You can also define the dialog model in JSON in your interaction model schema.

Steps of a multi-turn dialog or conversation

In an Alexa skill, a dialog with the user is a conversation with multiple turns in which Alexa asks questions and the user responds with the answers. The conversation is tied to a specific intent representing the user's overall request. The questions and answers are intended to gather, validate, and confirm slot values. The conversation continues until all slots needed for the intent are filled and confirmed according to the rules defined in the dialog model.

The questions Alexa asks during the conversation fall into four categories:

  • Slot elicitation: Ask the user for a slot value. The user answers with a slot value or a full utterance including the slot value. Examples of slot elicitation questions:
    • What city are you leaving from? (Eliciting the value for a fromCity slot.)
    • Where are you traveling to? (Eliciting the value for a toCity slot.)
    • When did you want to travel? (Eliciting the value for a travelDate slot.)
  • Slot confirmation: Ask the user to confirm that a single slot value previously provided (or set programmatically) is correct. The user answers with "yes" or "no". Examples of slot confirmation questions:
    • You said you're leaving from Seattle, right? (Confirming the fromCity value.)
    • Did you want to travel to Portland? (Confirming the toCity value.)
    • You're traveling on April 21st, right? (Confirming the travelDate value.)
  • Intent confirmation: Ask the user to verify that all the information gathered for the intent is correct before fulfilling the intent. As with slot confirmation, the user answers with "yes" or "no". Examples of intent confirmation questions:
    • I'm saving your trip from Seattle to Portland on April 21st. Is that OK? (Confirming the entire PlanMyTrip intent.)
  • Slot validation: Check the slot value against pre-defined rules and prompt the user if it fails. The user can then respond with a corrected value. Example:
    • I can't plan a trip for a date that has passed, so please tell me a date in the future (Prompt after user provided a date before today for the travelDate slot.)

The dialog for a particular intent might include all of these steps or only some of them. For instance, a dialog could include slot elicitation, but not use slot or intent confirmation.

A dialog can also involve multiple intents. The handler for the intent that started the dialog can pass control to a second intent that continues the dialog with a different set of questions.

About managing the conversation with the user

There are three main scenarios for handling a multi-turn conversation with the user in your skill:

  1. Delegate the dialog to Alexa. In this case, Alexa uses the prompts defined in the dialog model.
  2. Control each step of the dialog yourself using Dialog.ElicitSlot, Dialog.ConfirmSlot, and Dialog.ConfirmIntent.
  3. Combine both options. In this case, you delegate the dialog on some turns, but take control on others when necessary.

Delegate the dialog to alexa

This option lets you focus most of your coding efforts on the logic for fulfilling the user's request, rather than writing all the code to ask the user for slot values yourself. You can delegate the dialog automatically, or handle it manually with the Dialog.Delegate directive.

With auto delegation, Alexa completes all the dialog steps based on the dialog model, then sends your skill a single IntentRequest when it is done. With this option, you do not need to use the Dialog directives.

With manual delegation, Alexa sends your skill an IntentRequest for each turn of the conversation. The request includes a dialogState property that indicates whether there may be additional steps in the dialog (STARTED or IN_PROGRESS) or if all the steps are complete (COMPLETED). If the dialog is COMPLETED, this means that the IntentRequest has all the required slot values and confirmations from the user and all slot values are validated according to your defined rules. If the dialog is not yet complete, you return the Dialog.Delegate directive. Alexa determines the next step in the dialog and uses the prompts defined in the dialog model to elicit slot values, confirm slot values, validate slot values, or confirm the entire intent.

You cannot combine the Dialog.Delegate directive with any APL directives or APL requests. To display visuals on a screen during the dialog, control the dialog manually in your skill code.

Once the conversation is complete, the incoming IntentRequest has a dialogState of COMPLETED. All required information is now available in the intent's slot values. Your skill can fulfill the user's request at this point.

Control the dialog in your skill code

In this option, your code checks for slot values and confirmation status, determines the next step in the conversation, and returns the appropriate directives (Dialog.ElicitSlot, Dialog.ConfirmSlot, or Dialog.ConfirmIntent).

You need to determine the status and next steps in your own code. If your skill meets the requirements to use the Dialog directives, the IntentRequest sent to your skill does include dialogState. However, this is set to either STARTED (when the intent is invoked) or IN_PROGRESS. The COMPLETED status is only possible when you use Dialog.Delegate or auto delegation.

Note that the directives do not use the prompts defined in your dialog model in this scenario. For instance, when you return Dialog.ElicitSlot, you must include the prompt in your response. Dialog.ElicitSlot does use the utterances you provide for the slot. Alexa biases the interaction model to listen for the utterances defined for the slot, so it is important to provide good utterances when you define the dialog model.

Also note that Dialog.ElicitSlot does not perform any slot validation. If you want to define slot validation rules and prompt the user when they provide incorrect values, delegate the dialog to Alexa.

When you control the dialog in this way, you can include the Alexa.Presentation.APL.RenderDocument directive alongside the Dialog.ElicitSlot, Dialog.ConfirmSlot, or Dialog.ConfirmIntent directives, so you can display information relevant to the dialog on the screen. You can also return these directives from APL requests, so your overall dialog can incorporate both touch events and voice.

Both delegate and control the dialog manually

You can combine the two main options. Depending on the incoming IntentRequest, your code would take one of these actions:

  • Return Dialog.Delegate to let Alexa handle the next step.
  • Return one of the other directives (such as Dialog.ElicitSlot) to take control of the dialog yourself.

For an example of this scenario, see Manually delegate to alter the conversation at run-time.

Change the intent or update slot values during the dialog

Each of the Dialog directives includes an updatedIntent property that can take an Intent object. Use this to:

  • Trigger a dialog on a completely different intent. For example, after completing the dialog for a BookFlight intent, you could return Dialog.Delegate with updatedIntent set to BookRentalCar to start new dialog.
  • Set or change any slot values in code before continuing with the dialog. This can reduce the number of questions Alexa must ask to fulfill the intent, which improves the user experience.

    For instance, you can set slot values based on user defaults or other information you are persisting. Combine this with the Dialog.Delegate or Dialog.ConfirmSlot directives.

  • Set or change the confirmationStatus for a slot or for the entire intent.
  • Set or change slot values and confirmation statuses based on data provided by touch events when using Alexa Presentation Language to display content on the screen. For example, when the user selects a list item by touching the screen, your skill can get a UserEvent request with information about the selected item. You can use this to build an intent object, set the slot values as needed, and return a Dialog directive to continue the conversation.

    Since the UserEvent request does not include an intent, you do need to keep track of the current intent in the session.

Pass a new intent

When you use updatedIntent to change to a different intent, the directive acts against the new intent instead of the original:

…earlier dialog for the BookFlight intent
Alexa: OK, I've booked your flight. Do you want to also reserve a rental car?
User: Yes (Skill receives an AMAZON.YesIntent.)

Skill returns Dialog.Delegate with updatedIntent set to BookRentalCar.
Alexa: OK, lets book your car. What size car would you like, compact, mid-size, or full-size? (Slot elicitation dialog step for sizeOfCar slot on the BookRentalCar intent.)

When you use updatedIntent like this, note the following:

  • You can set slot values on the new intent object before you return the Dialog directive. This lets you carry over user information from the original intent to the new intent.
  • When you do set slot values on the new intent, be sure to include all slots defined in the interaction model for the intent, even those you want to leave empty. For example, if the intent has four slots and you want to set the value of just one, you still must include all four slots.
  • You can include text for Alexa to speak in the outputSpeech object for all Dialog intents. For Dialog.Delegate, Alexa speaks this text before speaking the prompts defined in the dialog. For the other directives, Alexa uses this text to prompt for the elicitation or confirmation.
  • Any text provided in the reprompt object is ignored and not used.
  • Set shouldEndSession to false or leave the property out of the response completely so that the session can remain open to continue the dialog.
  • You can also return any of the Dialog directives with an updatedIntent from a LaunchRequest. This can be useful to start your skill flow with a default action rather than asking the user what they want to do.
  • You can return Dialog.ElicitSlot, Dialog.ConfirmSlot, Dialog.ConfirmIntent, or Dialog.UpdateDynamicEntities from an Alexa.Presentation.APL.UserEvent request. This can be useful to start or continue a dialog based on the user's interactions with the screen.

Set or change data on the original intent

When you use updatedIntent to set or change data on the original intent, make sure that the intent name and full set of slots matches the intent sent to your skill. You can update the Intent object originally sent to your skill with the new slot values or confirmation status values and then just pass it back to the directive. Include all of the slots, including any empty slots you are not changing.

For an example of this scenario, see Manually delegate the dialog to set default values.

Directives

The following table summarizes the Dialog directives. See the sections below for details about each directive.

If your skill does not meet the requirements to use the Dialog directives, returning any of these directives causes an error.

Directive Description

Dialog.Delegate

Sends Alexa a command to handle the next turn in the dialog with the user. This directive is a valid return type depending on the combination of dialogState and updatedIntent:

  • When dialogState is either STARTED OR IN_PROGRESS, updatedIntent can be set to either the original intent or a new intent.
  • When dialogState is COMPLETED, you must also set updatedIntent to a different intent. If updatedIntent is not present or is set to the original intent, returning Dialog.Delegate for a COMPLETED dialog causes an error.

Dialog.ElicitSlot

Sends Alexa a command to ask the user for the value of a specific slot. Specify the name of the slot to elicit in the slotToElicit property. Provide a prompt to ask the user for the slot value in an OutputSpeech object in the response.

Dialog.ConfirmSlot

Sends Alexa a command to confirm the value of a specific slot before continuing with the dialog. Specify the name of the slot to confirm in the slotToConfirm property. Provide a prompt to ask the user for confirmation in an OutputSpeech object in the response. Be sure repeat back the value to confirm in the prompt.

Dialog.ConfirmIntent

Sends Alexa a command to confirm the all the information the user has provided for the intent before the skill takes action. Provide a prompt to ask the user for confirmation in an OutputSpeech object in the response. Be sure to repeat back all the values the user needs to confirm in the prompt.

Dialog.UpdateDynamicEntities

Adapts your interaction model at runtime. This directive augments your skill's predefined static catalogs by allowing your skill to dynamically create new entities.

Delegate directive

Sends Alexa a command to handle the next turn in the dialog with the user. This directive is a valid return type depending on the combination of dialogState and updatedIntent:

  • When dialogState is either STARTED OR IN_PROGRESS, updatedIntent can be set to either the original intent or a new intent.
  • When dialogState is COMPLETED, you must also set updatedIntent to a different intent. If updatedIntent is not present or is set to the original intent, returning Dialog.Delegate for a COMPLETED dialog causes an error.

Syntax

{
  "type": "Dialog.Delegate",
  "updatedIntent": {
    "name": "string",
    "confirmationStatus": "NONE",
    "slots": {
      "SlotName": {
        "name": "SlotName",
        "value": "string",
        "resolutions": {},
        "confirmationStatus": "NONE"
      }
    }
  }
}

Note that a Slot object for an intent may or may not include the resolutions property shown in the JSON syntax. This depends on the slot type. The presence or absence of the resolutions property has no effect on any of the Dialog directives.

Parameter Description Type Required

type

Set to Dialog.Delegate.

string

Yes

updatedIntent

An intent object. Use this to change intents during the dialog or set slot values and confirmation status. See Change the intent or update slot values during the dialog. If you don't need to change the intent, slot values, or confirmation statuses, you can leave this property out of your response.

Returning Dialog.Delegate with a different intent in updatedIntent is equivalent to the user invoking the intent directly. If auto delegate is enabled, your skill receives a single IntentRequest once the dialog for the new intent is complete. If auto delegate is not enabled, your skill receives an IntentRequest for each turn of the dialog. If the new intent uses the same slots as the original, be sure to set any filled slot values on the new intent to prevent Alexa from asking the user for the same values again.

object

No

Details

Alexa determines the next step in the dialog based on the dialog model. In a dialog for an intent with multiple slots, Alexa elicits, validates values, and confirms (if necessary) each slot in the order defined in the dialog model. Intent confirmation (when configured) happens once all required slots have values.

You can use slot validation with slots that are not required, so you can validate optional values if they are provided, but not force the user to fill those slots. In this case, Dialog.Delegate accepts a blank slot value and does not perform any validation or elicitation on the non-required slot. If the user does provide a value for the slot, Dialog.Delegate uses the validation rules and prompts normally.

When you include OutputSpeech in your response, Alexa speaks the outputSpeech before the prompts defined in the dialog model. This can be a useful way to create a transition when you change intents, although you can use outputSpeech even when not changing intents. Any speech included in the reprompt is ignored. Alexa uses the prompts in the dialog model to re-prompt during the dialog.

Delegate and Alexa Presentation Language

  • You cannot include any APL directives in the same response as Dialog.Delegate.
  • You cannot return Dialog.Delegate from any APL requests.

Example interaction

(Back up to Dialog Directives)

ElicitSlot directive

Sends Alexa a command to ask the user for the value of a specific slot. Specify the name of the slot to elicit in the slotToElicit property. Provide a prompt to ask the user for the slot value in an OutputSpeech object in the response.

If your skill does not meet the requirements to use the Dialog directives, returning Dialog.ElicitSlot causes an error.

Syntax

{
  "type": "Dialog.ElicitSlot",
  "slotToElicit": "string",
  "updatedIntent": {
    "name": "string",
    "confirmationStatus": "NONE",
    "slots": {
      "SlotName": {
        "name": "SlotName",
        "value": "string",
        "resolutions": {},
        "confirmationStatus": "NONE"
      }
    }
  }
}

Note that a Slot object for an intent may or may not include the resolutions property shown in the JSON syntax. This depends on the slot type. The presence or absence of the resolutions property has no effect on any of the Dialog directives.

This example illustrates returning Dialog.ElicitSlot to ask for the fromCity slot value. Note that the OutputSpeech object is used for the prompt.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "outputSpeech": {
      "type": "PlainText",
      "text": "From where did you want to start your trip?"
    },
    "shouldEndSession": false,
    "directives": [
      {
        "type": "Dialog.ElicitSlot",
        "slotToElicit": "fromCity",
        "updatedIntent": {
          "name": "PlanMyTrip",
          "confirmationStatus": "NONE",
          "slots": {
            "toCity": {
              "name": "toCity",
              "confirmationStatus": "NONE"
            },
            "travelDate": {
              "name": "travelDate",
              "confirmationStatus": "NONE",
              "value": "2017-04-21"
            },
            "fromCity": {
              "name": "fromCity",
              "confirmationStatus": "NONE"
            },
            "activity": {
              "name": "activity",
              "confirmationStatus": "NONE"
            },
            "travelMode": {
              "name": "travelMode",
              "confirmationStatus": "NONE"
            }
          }
        }
      }
    ]
  }
}

Parameter Description Type Required

type

Set to Dialog.ElicitSlot.

string

Yes

slotToElicit

The name of the slot to elicit.

string

Yes

updatedIntent

An intent object. Use this to change intents during the dialog or set slot values and confirmation status. See Change the intent or update slot values during the dialog. If you don't need to change the intent, slot values, or confirmation statuses, you can leave this property out of your response.

When you switch intents with this parameter, Alexa attempts to elicit the specified slot value on the new intent. The next IntentRequest to your skill will be the new intent, not the original.

object

No

Details

You must include the prompt to ask the user for the slot value in the OutputSpeech object. The directive does not use the prompts defined in the dialog model.

Dialog.ElicitSlot uses the user utterances you provide for the slot in your dialog model. Alexa biases the interaction model to listen for the utterances defined for the slot, so it is important to provide good utterances when you define the dialog model.

ElicitSlot and Alexa Presentation Language

Example interaction

(Back up to Dialog Directives)

ConfirmSlot directive

Sends Alexa a command to confirm the value of a specific slot before continuing with the dialog. Specify the name of the slot to confirm in the slotToConfirm property. Provide a prompt to ask the user for confirmation in an OutputSpeech object in the response. Be sure repeat back the value to confirm in the prompt.

If your skill does not meet the requirements to use the Dialog directives, returning Dialog.ConfirmSlot causes an error.

Syntax

{
  "type": "Dialog.ConfirmSlot",
  "slotToConfirm": "string",
  "updatedIntent": {
    "name": "string",
    "confirmationStatus": "NONE",
    "slots": {
      "string": {
        "name": "string",
        "value": "string",
        "resolutions": {},       
        "confirmationStatus": "NONE"
      }
    }
  }
}

Note that a Slot object for an intent may or may not include the resolutions property shown in the JSON syntax. This depends on the slot type. The presence or absence of the resolutions property has no effect on any of the Dialog directives.

This example illustrates returning Dialog.ConfirmSlot to confirm the fromCity slot value. Note that the OutputSpeech object is used for the prompt.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "outputSpeech": {
      "type": "PlainText",
      "text": "You said you're leaving Seattle, right?"
    },
    "shouldEndSession": false,
    "directives": [
      {
        "type": "Dialog.ConfirmSlot",
        "slotToConfirm": "fromCity",
        "updatedIntent": {
          "name": "PlanMyTrip",
          "confirmationStatus": "NONE",
          "slots": {
            "toCity": {
              "name": "toCity",
              "confirmationStatus": "NONE"
            },
            "travelDate": {
              "name": "travelDate",
              "confirmationStatus": "NONE",
              "value": "2017-04-21"
            },
            "fromCity": {
              "name": "fromCity",
              "value": "Seattle",
              "confirmationStatus": "NONE"
            },
            "activity": {
              "name": "activity",
              "confirmationStatus": "NONE"
            },
            "travelMode": {
              "name": "travelMode",
              "confirmationStatus": "NONE"
            }
          }
        }
      }
    ]
  }
}

Parameter Description Type Required

type

Set to Dialog.ConfirmSlot.

string

Yes

slotToConfirm

The name of the slot to confirm.

string

Yes

updatedIntent

An intent object. Use this to change intents during the dialog or set slot values and confirmation status. See Change the intent or update slot values during the dialog. If you don't need to change the intent, slot values, or confirmation statuses, you can leave this property out of your response.

When you switch intents with this parameter, Alexa attempts to confirm the specified slot value on the new intent. Be sure the intent object you pass to updatedIntent has a value in the slot you want to confirm. The next IntentRequest to your skill will be the new intent, not the original.

string

No

Details

When you return Dialog.ConfirmSlot, include the prompt to ask the user for confirmation in the OutputSpeech object. The directive does not use the prompts defined in the dialog model.

After Alexa speaks your prompt from the OutputSpeech, the user can respond with "yes" or "no." Alexa then sends your skill the intent with an updated confirmationStatus property on the specific slot to indicate the user's response (CONFIRMED or DENIED).

The user can deny the confirmation twice, after which the session ends.

ConfirmSlot and Alexa Presentation Language

Example interactions

(Back up to Dialog Directives)

ConfirmIntent directive

Sends Alexa a command to confirm the all the information the user has provided for the intent before the skill takes action. Provide a prompt to ask the user for confirmation in an OutputSpeech object in the response. Be sure to repeat back all the values the user needs to confirm in the prompt.

If your skill does not meet the requirements to use the Dialog directives, returning Dialog.ConfirmIntent causes an error.

Syntax

{
  "type": "Dialog.ConfirmIntent",
  "updatedIntent": {
    "name": "string",
    "confirmationStatus": "NONE",
    "slots": {
      "string": {
        "name": "string",
        "value": "string",
        "resolutions": {},               
        "confirmationStatus": "NONE"
      }
    }
  }
}

Note that a Slot object for an intent may or may not include the resolutions property shown in the JSON syntax. This depends on the slot type. The presence or absence of the resolutions property has no effect on any of the Dialog directives.

This example illustrates returning Dialog.ConfirmIntent to confirm entire intent. Note that the OutputSpeech object is used for the prompt. In this example, the three required slots (toCity, fromCity, and travelDate) also used confirmation and were confirmed on previous turns of the dialog. The other two slots (activity and travelMode) have been filled, but did not need any confirmation.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "outputSpeech": {
      "type": "PlainText",
      "text": "I'm saving your trip from Seattle to Portland on April 21st. Is that OK?"
    },
    "shouldEndSession": false,
    "directives": [
      {
        "type": "Dialog.ConfirmIntent",
        "updatedIntent": {
          "name": "PlanMyTrip",
          "confirmationStatus": "NONE",
          "slots": {
            "toCity": {
              "name": "toCity",
              "value": "Portland",
              "confirmationStatus": "CONFIRMED"
            },
            "travelDate": {
              "name": "travelDate",
              "confirmationStatus": "CONFIRMED",
              "value": "2017-04-21"
            },
            "fromCity": {
              "name": "fromCity",
              "value": "Seattle",
              "confirmationStatus": "CONFIRMED"
            },
            "activity": {
              "name": "activity",
              "value": "hiking"
              "confirmationStatus": "NONE"
            },
            "travelMode": {
              "name": "travelMode",
              "value": "driving"
              "confirmationStatus": "NONE"
            }
          }
        }
      }
    ]
  }
}

Parameter Description Type Required

type

Set to Dialog.ConfirmIntent.

string

yes

updatedIntent

An intent object. Use this to change intents during the dialog or set slot values and confirmation status. See Change the intent or update slot values during the dialog. If you don't need to change the intent, slot values, or confirmation statuses, you can leave this property out of your response.

When you switch intents with this parameter, Alexa attempts to confirm the new intent. Be sure to set any relevant slot values on the intent before you return the directive. The next IntentRequest to your skill will be the new intent with the confirmationStatus based on the user's response, not the original.

object

No

Details

Use this directive after your skill has gathered all the required slots you need to fulfill an intent, but you want to give the user one more opportunity to confirm that it is correct before continuing. This is common for skills that order products or make reservations.

When you return Dialog.ConfirmIntent, include the prompt to ask the user for confirmation in the OutputSpeech object. The directive does not use the prompts defined in the dialog model.

After Alexa asks the user to confirm the information, the user can respond with "yes" or "no." Alexa then sends your skill the intent with an updated intent.confirmationStatus property to indicate the user's response (CONFIRMED or DENIED).

ConfirmIntent and Alexa Presentation Language

Example interaction

(Back up to Dialog Directives)

UpdateDynamicEntities directive

Adapts your interaction model at runtime. This directive augments your skill's predefined static catalogs by allowing your skill to dynamically create new entities.

For details, see Use Dynamic Entities for Customized Interactions.

Service Interface Reference (JSON)

Request Format and Standard Request Types:

Interfaces:


Was this page helpful?

Last updated: Nov 28, 2023