Create the Interaction Model for Your Skill

With the Alexa Skills Kit, you can create skills with a custom interaction model. You implement the logic for the skill, and you also define the voice interface through which users interact with the skill. To define the voice interface, you map users' spoken input to the intents your cloud-based service can handle.

To declare this mapping, you supply the following inputs:

  1. Intents: An intent represents an action that fulfills a user's spoken request. Intents can optionally have arguments called slots. Intents are specified in a JSON structure called the intent schema.
  2. Sample utterances: A set of likely spoken phrases mapped to the intents. This should include as many representative phrases as possible.
  3. Custom slot types: A representative list of possible values for a slot. Custom slot types are used for lists of items that are not covered by one of Amazon's built-in slot types.
  4. Dialog model (optional): A structure that identifies the steps for a multi-turn conversation between your skill and the user to collect all the information needed to fulfill each intent. This simplifies the code you need to write to ask the user for information.

This document defines these components and explains how to create them within the developer console.

About intents, slots, and dialogs

This section provides a brief overview of the components of an interaction model:

Intents and slots

An intent represents an action that fulfills a user's spoken request. Intents can optionally have arguments called slots. For example, a skill for planning a trip might define an intent named PlanMyTrip that has slots named fromCity, toCity, and travelDate. A user can then say:

User: Alexa, ask Plan My Trip to plan a trip from Seattle to Portland on Friday.

The Alexa service sends the Plan My Trip service a PlanMyTrip intent with the value "Seattle" in the fromCity slot, "Portland" in the toCity slot and the date for the next upcoming Friday in the travelDate slot. The service can then save this information and send back text to convert to speech.

Slots are defined with different types. The travelDate slot in the above example uses Amazon's built-in AMAZON.DATE type to convert words that indicate dates (such as "today" and "next friday") into a date format, while both fromCity and toCity use the built-in AMAZON.US_CITY slot. If you extended this skill to ask the user what activities they plan to do on the trip, you might add a custom LIST_OF_ACTIVITIES slot type to reference a list of activities such as "hiking", "shopping", "skiing", and so on.

Amazon provides built-in support for a large library of slot types. This includes:

All built-in types have the prefix AMAZON.

To learn how to create intents and slots in the developer console, see Create Intents, Utterances, and Slots.

For more about designing skills and identifying your intents and slots, see the Alexa Design Guide.

Sample utterances

The sample utterances specify the words and phrases users can say to invoke your intents. Each intent is mapped to several utterances. Slots are indicated within the utterances with curly brackets. For example, this utterance for PlanMyTrip includes the toCity slot:

i want to visit {toCity}

To learn how to create utterances in the developer console, see Create Intents, Utterances, and Slots.

For more about writing good sample utterances, see the Alexa Design Guide.

Multi-turn conversations and the dialog model

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.

You can use the developer console to define 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.

To use the dialog model in your skill, return the Dialog.Delegate directive. Alexa then determines the next step and uses the defined prompts to ask the user for information. This lets you delegate the conversation to Alexa, rather than writing your own code to ask the user for slot values and confirmations.

You can also manage the conversation manually, or use a combination of delegation and other options. See About Managing the Conversation with the User.

To learn how to define a dialog model in the developer console, see Define the Dialog to Collect and Confirm Required Information.

High-level steps to create the interaction model and dialog model

The developer console is designed around defining each intent, its slots, its utterances, and (optionally) the prompts Alexa uses when conversing with the user to collect and confirm the slot values.

Once you know an intent you want to create for your skill, complete the following high-level steps in the developer console. Click the link in each step for more details.

  1. Create or edit a skill that includes the custom interaction model.
  2. Create an intent and write some initial utterances. An intent represents a specific user request (for example, PlanMyTrip intent for gathering information about a trip to save in a list).
  3. Review your initial utterances and identify the words or phrases that represent variable information. Create new intent slots for these words and replace the words with slot notation in the utterances.
  4. Choose or create the appropriate slot types for the slots you have identified.
  5. For each intent slot, determine whether the slot value is required in order to fulfill the request. Write the prompts and utterances Alexa uses in the conversation to elicit the slot.
  6. For each required slot, determine whether the user must explicitly confirm the slot value before your skill completes the request. Write the prompts Alexa should use to ask for confirmation.
  7. For each slot (required or not), determine whether you need to define validation rules to guide users to provide acceptable values. Set up the rules and write the prompts Alexa should use to ask for corrected values.
  8. For the entire intent, decide whether the user must explicitly confirm the action before your skill completes the request. Write the prompts Alexa should use to ask for confirmation.
  9. When you are finished defining the intents, save and build the interaction model and dialog model.

If you include any of the dialog model components (required slots, slot confirmation, intent confirmation, or slot validation rules) your code needs to return the Dialog.Delegate directive to let Alexa use your prompts to ask the user for the required slots and confirmations. Also see About Managing the Conversation with the User for other ways to collect and confirm user information.

Save and build the model

As you create and edit your interaction model and dialog model, save your work with the Save Model button. This saves your data, but does not build the model.

When you are ready to test your interaction model, go to any of the sections under Custom, Interaction Model. Then click Build Model to validate, save, and build your interaction model. You can continue to make changes, but they won't be reflected in the build.

The build happens in two stages:

  1. Quick build – The quick build is done in as little as a few seconds, and enables you to begin testing your skill. When the quick build succeeds, the developer console displays a message. After the quick build, the majority of sample utterances, though not necessarily all, work correctly. The following are not available for testing until the full build is done:
  2. Full build – The full build can take up to one minute. After the full build is done, all the parts of the model are built and ready to be tested.

You must successfully build the model, either a quick build or a full build, before you can test it. The developer console displays a success message when each stage of the build is done. You can also check the status of the build with the Alexa Skills Kit Command Line Interface (ASK CLI) get-skill-status command or the Skill Management API (SMAPI) GET skill status request.

View and edit the JSON code for the interaction model and dialog model

When using the developer console, you can see your invocation name, intent schema, sample utterances, and dialog model in JSON format. You can make changes directly to this code and apply them to your interaction model.

Click JSON Editor to see the JSON version of your model. If you make any changes, be sure to click Save Model to apply the changes to your model.

For details about the JSON format for the interaction model, see Interaction Model Schema.

Use a previous version of the interaction model

Each time you make changes to an interaction model and then build it, the developer console saves it as a version. You can use the developer console to revert to a version of the interaction model that was built previously.

To view versions and revert to a previously built version:

  1. On the Build tab of the developer console, go to any of the sections under Custom, Interaction Model.
  2. Near the top of the page, click View Model Versions.
  3. Select a version, then click Select Version.
  4. Click Revert.

Test and improve your interaction model

As you build your skill, you can test and improve your interaction model.

  • Check for utterance conflicts that may cause Alexa to send the wrong intent to your skill.
  • Use the utterance profiler to test individual utterances. You can enter utterances and see how they resolve to the intents and slots.
  • Use the NLU evaluation tool to create and run a set of tests against your model. With this tool, you create a set of utterances mapped to the intent and slots you expect for each one. Then you run an evaluation and test how well you skill's natural language understanding (NLU) model performs against your expectations. This can be especially useful for regression testing as you iterate on your interaction model.

These tools do not call your endpoint, so you can use them any time after you build your interaction model.

Interaction model limits

The interaction model for a custom skill has the following limits:

  • Number of intents in a skill – 250
  • Number of slot types and intents combined – 350
  • Number of characters allowed in a single slot value – 140
  • Number of characters allowed for a slot value synonym – 140

Intent and slot name requirements

  • Intent and slot names can contain case-insensitive alphabetical characters and underscores. No numbers, spaces or special characters are allowed.

    Note that the built-in intents use the AMAZON namespace, so the name for an intent uses a period. For example: AMAZON.HelpIntent. This notation is valid for specifying the AMAZON namespace only. Periods can't be used in custom intent names.

  • Intent and slot names can't overlap with each other in the the interaction model. If you use a name for an intent, you can't use that same name for a slot.
  • Intent and slot names are case insensitive, so the intent name "ABC" can't be used with the slot name "abc".
  • The same slot name can be used in multiple intents as long as it has the same slot type in each and represents the same entity. For example, you could use the name travelDate for a slot in multiple intents, but in each intent, it represents the travel date and has the same AMAZON.Date type.
  • The built-in intent AMAZON.SelectIntent has four slots. When you include AMAZON.SelectIntent in your interaction model, you can't use those slot names as the name for any of your custom intents. For example, you can't name an intent ListPosition.

    You can use the slot names for slots in your own custom intent as long as you use the same slot types. For example, you could use ListPosition as the name of a slot in your custom intent as long as you assign it the AMAZON.Ordinal slot type. For details about the AMAZON.SelectIntent slots, see AMAZON.SelectIntent slots.