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. All sample utterances must provide the user with a response that's relevant and grammatically correct, in the language for the selected locale, and free of errors. Include as many representative phrases as possible.
  3. Custom slot types: A representative list of possible values for a slot. Use custom slot types for lists of items that aren't 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. The dialog model simplifies the code you 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 dialogues

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 preceding 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.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.

After 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. After you define the intents, save and build the models.

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

Save and build the model

As you create and edit your interaction model and dialog model, save your work with the Save button. This saves your data, but doesn't build the model.

To validate and build your interaction model, go to any of the sections under CUSTOM >Interaction Model, click Save, and then click Build skill. Or you can go to CUSTOM, and then under Building your skill, click 3. Build Model. While the model builds, you can continue to make changes to your model, but the changes aren't included in the current build.

The build happens in two stages:

  1. Quick build – The quick build completes 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 features aren't available for testing until the full build completes:
  2. Full build – The full build can take up to one minute. After the full build completes, all the parts of the model are built and ready to be tested.

Before you test your skill, you must successfully build the model, either a quick build or a full build. The developer console displays a success message when each stage of the build completes. You can also check the status of the build with the Alexa Skills Kit Command Line Interface (ASK CLI) get-skill-status subcommand.

For more details about building the models in the developer console, see Build your skill.

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

In 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.

To see the JSON version of your model, click CUSTOM > JSON Editor. If you make any changes in the editor, be sure to click Save 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 the model as a new version. You can use the developer console to revert to a version of the interaction model. To view versions and revert to another version, see Build history.

Test and improve your interaction model

As you build your skill, you can test and improve your interaction model before you write any skill code. For details, see Test Your Interaction Model.

Interaction model limits

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

  • Size – 1.5 MB
  • 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 type names can contain case-insensitive alphabetical characters and underscores. Don't use numbers, spaces or special characters.
  • Intent and slot names can't overlap with each other in 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. Don't use the intent name "ABC" with the slot name "abc".
  • You can use the same slot name 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.

Was this page helpful?

Last updated: Aug 08, 2024