Your Alexa Dashboards Settings

Define the Interaction Model in JSON and Text

With the Alexa Skills Kit, you can add new capabilities to Alexa by creating custom skills. When you create a custom skill, 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.
  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.

You enter this information in the developer portal on the Interaction Model page. For details, see Registering and Managing Custom Skills in the Developer Portal.

The following sections explain how to use each of these resources to define an effective voice interface. If your skill also has a screen interface, then your voice interface must also be designed to also work with a screen. See: Voice Design Guide

Intent Schema

An intent represents an action that fulfills a user’s spoken request. Intents can optionally have arguments called slots. For example, the intent schema for “Daily Horoscopes” might define an intent named GetHoroscope that has slots named Sign and Date. A user can then say:

User: Alexa, ask Daily Horoscopes for the horoscope for Pisces today.

The Alexa service sends the Daily Horoscopes service a GetHoroscope intent with the value “pisces” in the Sign slot and the current date in the Date slot. The service can then look up today’s horoscope for Pisces and send back text to convert to speech.

You define the set of valid intents in a JSON structure called an intent schema. For example, the following intent schema defines two intents: GetHoroscope and GetLuckyNumbers:

{
  "intents": [
    {
      "intent": "GetHoroscope",
      "slots": [
        {
          "name": "Sign",
          "type": "LIST_OF_SIGNS"
        },
        {
          "name": "Date",
          "type": "AMAZON.DATE"
        }
      ]
    },
    {
      "intent": "GetLuckyNumbers"
    }
  ]
}

Each intent has two properties:

  • The intent property gives the name of the intent.
  • The slots property lists the slots associated with that intent.

In the above example, the GetHoroscope intent defines two slots, one named Sign, the other named Date.

Slots are defined with different types. For instance, the Sign slot in the above example is defined as a custom type LIST_OF_SIGNS to reference a list of horoscope sign values provided for the slot (Aries, Capricorn, etc.). The Date slot uses Amazon’s built-in AMAZON.DATE type to convert words that indicate dates (such as “today”) a date format.

Note that the Alexa Skills Kit provides a library of built-in intents for common actions. If you want to implement these, you include them in your intent schema just like your own custom intents. For details, see Implementing the Built-in Intents.

Slot Types

Each slot you include in an intent must have a slot type. This can be either a built-in slot type or a custom slot type.

Built-in Slot Types

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

All built-in types have the prefix AMAZON.

You don’t need to provide sample values for the built-in slot types. Include the slot name in the sample utterances file as necessary. For other data types, a custom slot type is recommended.

An additional built-in slot type is supported just for English (US) skills: AMAZON.LITERAL. This type is primarily provided for compatibility with earlier versions of the Alexa Skills Kit.

Note that slot type behavior has changed since earlier versions of the Alexa Skills Kit. For information about the differences, backward compatibility, and migrating a skill from the previous version, see Migrating to the Improved Built-in and Custom Slot Types.

Custom Slot Types

A custom slot type defines a list of representative values for the slot. Custom slot types are used for lists of items that are not covered by Amazon’s built-in set of types and are recommended for most use cases. When using a custom type, you define the type and its values, and specify the name of the type as part of the intent definition.

For example, the custom slot type for a horoscope skill might be named LIST_OF_SIGNS and have these values:

Aries
Taurus
Gemini
Cancer
Leo
Pisces
Virgo
Libra
Scorpio
Sagittarius
Capricorn
Aquarius

The set of custom values can be anything supported by your skill’s handling of the slot as long as it can be spoken by a user, although words not found in a typical dictionary for the skill’s language may not be recognized.

Slot values are sent to your skill in written format. For example, both “fire h. d. 7” and “fire h. d. seven” would be sent to your skill as “Fire HD7”. For better recognition, acronyms and other phrases involving spoken letters should either be all caps (“HD”) or separated by periods and a space (“h. d. “). Using lowercase for initialisms may lead to unreliable recognition since the spoken form may not correctly be detected. See examples.

Note that a custom slot type is not the equivalent of an enumeration. Values outside the list are still returned if recognized by the spoken language understanding system. Although input to a custom slot type is weighted towards the values in the list, it is not constrained to just the items on the list. Your code still needs to include validation and error checking when using slot values. See the “Handling Possible Input Errors” section of Handling Requests Sent by Alexa.

For recommendations for custom slot type values, see Custom Slot Type Values.

A custom slot type can be used for multiple slots. For example, suppose the horoscope skill had an additional intent, MatchSign, that compared two Zodiac signs. This intent defines two slots, FirstSign and SecondSign. These slots can both use the same custom LIST_OF_SIGNS slot type:

{
  "intents": [
    {
      "intent": "GetHoroscope",
      "slots": [
        {
          "name": "Sign",
          "type": "LIST_OF_SIGNS"
        },
        {
          "name": "Date",
          "type": "AMAZON.DATE"
        }
      ]
    },
    {
      "intent": "MatchSign",
      "slots": [
        {
          "name": "FirstSign",
          "type": "LIST_OF_SIGNS"
        },
        {
          "name": "SecondSign",
          "type": "LIST_OF_SIGNS"
        }
      ]
    },
    {
      "intent": "GetLuckyNumbers"
    }
  ]
}

Sample Utterances

Each possible sample utterance is assigned to one of the defined intents. For example, the following snippet from a sample utterances file maps four possible phrases to the GetHoroscope intent, two phrases to the GetLuckyNumbers intent, and two phrases to the MatchSign intent (in practice, many more utterances are required than shown in this example):

GetHoroscope what is the horoscope for {Sign}
GetHoroscope what will the horoscope for {Sign} be on {Date}
GetHoroscope get me my horoscope
GetHoroscope {Sign}
...
GetLuckyNumbers what are my lucky numbers
GetLuckyNumbers tell me my lucky numbers
...
MatchSign do {FirstSign} and {SecondSign} get along
MatchSign what is the relationship between {FirstSign} and {SecondSign}

Note that you do not need to provide sample utterances for any of the built-in intents, such as AMAZON.HelpIntent.

Sample Utterance Syntax

Each line of a sample utterances file consists of two fields separated by tabs or spaces:

  • The name of the intent on the left.
  • The phrase a user might speak to signal that intent on the right.

Slots are arguments to intents. In each sample utterance, for all slot types except AMAZON.LITERAL, represent a slot value as the slot name in curly braces: {SlotName}. The AMAZON.LITERAL slot type also requires word values for the slot inline: {slot value|SlotName}.

For example, consider this sample in the file:

"what will the horoscope for {Sign} be on {Date}" 

In this utterance, the slots {Sign} and {Date} serve as arguments to the GetHoroscope intent, and are placed as variables in this utterance pattern. Possible values for {Sign} are taken from the custom list LIST_OF_SIGNS and possible values for {Date} are taken from the Alexa Skill Kit’s built-in support for dates. This allows the user to give input such as:

"what will the horoscope for Leo be on Tuesday" 

The Alexa Skills Kit automatically generalizes input based on the custom and built-in slot types so just the specification of one pattern allows all forms of input against that pattern. However, it’s still important to consider variations in the utterance patterns. For example, to cover the following utterance:

"what will the horoscope for libra be tomorrow" 

the following pattern should be added to the sample utterances file (where “on” is no longer necessary):

"what will the horoscope for {Sign} be {Date}". 

For more guidance on specifying utterance patterns, see Best Practices for Sample Utterances and Custom Slot Type Values.

An individual utterance does not need to use every slot defined for an intent. The schema for the GetHoroscope intent shown in the above example defines both a Sign slot and a Date slot. The utterance “what is the horoscope for {Sign}” only uses the Sign slot, while the utterance “get me my horoscope” doesn’t use any slots at all. When users speak these phrases, the same intent is sent, but with null slot values.

As a general practice, look out for typos and spelling errors. Don’t forget the apostrophe (‘) in “what’s” and “who’s”, and watch out for mistakes introduced by directly copying and pasting from written language sources.

Next Steps