Custom Interaction Model Reference (Intents, Slots, Sample Utterances)

The configuration for an Alexa skill must include the following components to define the voice interface:

  1. An Intent Schema: A JSON structure which declares the set of intents your service can accept and process.
  2. The Spoken Input Data:
    • Sample Utterances: A structured text file that connects the intents to likely spoken phrases and containing as many representative phrases as possible.
    • Custom Values (required for use with custom slots): A list of values for specific items used by your skill and referenced in the intents when using a custom slot type.

These inputs are entered in the Interaction Model section of an Alexa skill configuration. See Registering and Managing Custom Skills in the Developer Portal for details.

This document provides a reference for the JSON structure for defining intents and the plain text structure used to define custom slot types and sample utterances. For more about building your interaction model with these structures manually, see Define the Interaction Model in JSON and Text. For more about designing skills and identifying your intents and slots, see Design Process.

In addition, if you are including visual and touch interactions in your Alexa skill, the Intent Schema must reflect the additional intents that are required for these interactions to work correctly. The format of the interaction model otherwise remains the same for visual and touch interactions.

Intent Schema Syntax (JSON)

An intent schema is a JSON structure with the following syntax:

{
  "intents": [
    {
      "intent": "string",
      "slots": [
        {
          "name": "string",
          "type": "string"
        },
        {
          "name": "string",
          "type": "string"
        }
      ]
    }
  ]
}

Intent Schema Parameters

Parameter Meaning

"intents":[]

An array that specifies the list of intents that can be sent to the skill.

"intent":"string"

A string identifying the name of an intent.

The name of the intent can only contain case-insensitive alphabetical characters. No numbers, spaces or special characters are allowed. Intent names cannot overlap with any slot names in the schema.

Note that the built-in intents use the AMAZON namespace, so they are specified using a period, like this: AMAZON.HelpIntent. This notation is only valid for specifying the AMAZON namespace. Periods should not be used in other intent names.

For example, GetZodiacHoroscopeIntent is valid, while Get Zodiac Horoscope Intent, Zodiac.GetHoroscopeIntent and Get2015HoroscopeIntent are invalid.

"slots":[]

An array specifying the list of slots within an intent.

Each slot consists of two items: name and type

Note that slot names and intent names cannot overlap, even across all the intents in the schema. For instance, once you use a particular name for an intent, you cannot use that name for any slots in the schema. Also, intent and slot names are case insensitive, so the intent name “ABC” cannot be used with the slot name “abc”.

The same slot name can be used in multiple intents as long as it has the same type in each and represents the same entity. For example, a Sign slot might be used in different intents for a horoscope skill, but in every case, it represents a zodiac sign and has the same custom slot type.

This property is only needed if the intent has at least one slot.

Note that you cannot declare slots for the built-in intents.

"name":"string"

A string identifying the name of an individual slot. - The name of the slot can only contain case-insensitive alphabetical characters. No numbers, spaces or special characters are allowed. - For example, ZodiacSign is valid, while Zodiac Sign and 12-Month\_ZodiacSign are invalid.

"type":"string"

A string identifying the type of a slot. The slot type indicates how the Alexa service handles the slot data before sending the value to your service. You can create a custom slot type, or use one of many built-in slot types.

Custom Slot Type Syntax

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 (“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.

Custom Slot Type Name

The name of a custom slot type can contain alphabetic characters only. The only special character allowed is the underscore (“_”). The dot character (.) is allowed, but only when extending one of the built-in types that allows custom values. That is, you can define a custom slot type called AMAZON.US_CITY if you want to add additional cities to the list, but you cannot define a custom slot type called AMAZON.DATE or MYDEV.MY_CUSTOM_SLOT.

Custom Slot Type Values

A skill can have a total of 50,000 custom slot values, totaled across all custom slots used in the interaction model.

The slot values provided in requests to your service are provided in standard written form. Each value must be on its own line.

For example, the following table illustrates some example slot type values and how they are converted to written form when provided to your service. In this table, the Slot Value is the value you would provide in your list of custom slot values. The Spoken Form represents what the user says, and the Slot Value Output is the data sent to your service in the request.

Slot Value Spoken Form Slot Value Output
DJ d. j. DJ
PJ Harvey p. j. harvey PJ Harvey
two beers two beers 2 beers
four inch four inch 4”
4 inch four inch 4”
four star four star 4 star
4-star four star 4 star
all-in-one all in one all in 1
first amendment first amendment 1st amendment
John’s john’s John’s
Ford Motor co. ford motor company ford motor company
Cambridge Univ. cambridge univ Cambridge univ
Seattle, Washington seattle washington Seattle Washington
R&B r. and b. R&B
r. and b. r. and b. R&B
amazon.com amazon dot com amazon dot com
joe@example.com joe at example dot com joe at example dot com
Fire HD fire h. d. fire HD
Fire h.d. fire h. d. fire HD
Fire h. d. fire h. d. fire HD
Fire HD7 fire h. d. seven fire HD7
Fire HD 7 fire h. d. seven fire HD7

Note that acronyms and initialisms are indicated using all caps. Alternatively, periods may be used to separate the letters. Using lowercase without periods (such as “fire hd”) may lead to unreliable recognition since the spoken form may not be correctly detected.

In all other cases, capitalization does not matter – you can use uppercase or lowercase. Numbers may be either spelled out or numeric (e.g. “seven” or “7”).

Sample Utterances Syntax

Sample utterances map the phrases the user can speak to the intents you have defined. They are written as lines in a plain text file, using the following format:

IntentName  this is a sample utterance with no slots
IntentName  this is a sample utterance containing a {SlotName}
IntentName  this is a sample utterance containing a {SlotName} and {AnotherSlotName}

Note that the above format applies to all slot types except AMAZON.LITERAL. For AMAZON.LITERAL, you also need to specify a sample slot value:

IntentName  this is a sample utterance containing a {slot value|SlotName} using LITERAL

Sample Utterance Specification

Component Meaning and Rules
IntentName Every line starts with an intent name that matches an intent defined in the JSON intent schema. The intent name can only contain case-insensitive alphabetical characters

Follow the IntentName with one or more tabs or spaces to separate it from the sample utterance.
sample utterance Provide the phrase the user can speak to trigger the intent. If the phrase should set any slot values, include the slot definition in curly brackets as described in slot definition. The utterance can include multiple slots.

See Rules for Sample Utterances for more details.
{slot definition} Slots are identified with curly brackets using the syntax: {SlotName}. SlotName is the name of the slot defined in the intent schema.

For example, the following line defines a sample utterance for the intent GetHoroscope with a slot called Sign. This slot is defined with a custom slot type called LIST_OF_SIGNS that defines all twelve Zodiac signs.

GetHoroscope what is the horoscope for {Sign}

When the user speaks this phrase, your service receives a GetHoroscope intent with a slot named Sign containing the text value that the user spoke for the slot.

Similarly, the following line defines a sample utterance with two slots, the custom Sign slot, and a slot called Date, defined as AMAZON.DATE.

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

When the user speaks this phrase, your service receives a GetHoroscope intent with two slots: Sign and Date. The Date slot contains the value the user spoke for the slot, converted to a date.

The string for the SlotName can contain only case-insensitive alphabetical characters. It must match the name of a slot defined in the JSON intent schema.

Rules for Sample Utterances

While contents of any custom slot values can be entered in different forms (digits, abbreviations, etc.), the surrounding sample utterances need to follow certain rules, as follows. These rules also apply to any words specified inline in AMAZON.LITERAL slot values.

  • Numbers should be expressed as words and not digits (“five”, not “5”).
  • Acronyms and other phrases involving spoken letters should be separated by periods and spaces (“n. b. a.”, not “nba”).
  • Punctuation marks should not be included except in the special cases listed below. (“ten dollars”, not “$10”. “three point five stars”, not “3.5 stars”). Exceptions:
    • Include periods after letter abbreviations (“n. b. a.”, “e. t. a.”).
    • Include apostrophes in possessive and contractions (“romeo’s” and “i’m”).
    • Include hyphens that are word-internal (“man-eating”) but in no other cases.
  • If the word for a slot value may have apostrophes indicating the possessive, or any other similar punctuation (such as periods or hyphens) include those within the brackets defining the slot. Do not add 's after the closing bracket. For example:

    • For possessives
      • Use: "martini's" as a custom value for {Drink} and "tell me a {Drink} ingredients" in the sample utterances
      • Do not use: "tell me a {Drink}'s ingredients"
    • For hyphenated values
      • Use: editor-in-chief in the custom values and {Position} in the sample utterances
      • Do not use: editor in the custom values and {Position}-in-chief in the sample utterances

Example Interaction Model

The complete interaction model for a daily horoscope skill might look like the following:

Intent definition:

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

Custom slot type LIST_OF_SIGNS definition:

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

Corresponding sample utterances:

GetHoroscope what is the horoscope for {Sign}
GetHoroscope what will the horoscope for {Sign} be {Date}
GetHoroscope what will the horoscope for {Sign} be on {Date}
GetHoroscope get me my horoscope
GetHoroscope {Sign}
...
(many more sample utterances)

In this example:

  • Speaking the first phrase sends the skill a GetHoroscope intent with a slot named Sign containing the string value spoken for the {Sign} slot value.
  • Speaking the second and third phrase sends the same GetHoroscope intent, with values for two slots: Sign and Date.
  • Speaking the fourth phrase sends the same GetHoroscope intent, but with no slot values.
  • Speaking the fifth phrase sends the same GetHoroscope intent with the Sign slot value (note that this utterance consists of just a slot value).

Including the optimal set of sample utterances for your skill increases Alexa’s ability to send your skill the correct intents and slots. For guidelines, see Best Practices for Sample Utterances and Custom Slot Type Values.

LITERAL Slot Type Reference

AMAZON.LITERAL passes the recognized words for the slot value with no conversion. You must define a set of representative slot values as part of your sample utterances. This is primarily provided for compatibility with earlier versions of the Alexa Skills Kit.

When using AMAZON.LITERAL, you must include sample slot values within the curly brackets defining the slot in the utterance:

StatusUpdate    post the update {out at lunch|UpdateText}

Note the following rules and recommendations.

Include samples with different numbers of words for the slot value:

  • Samples with the minimum number of words you expect for the slot value.
  • Samples with the maximum number of words for the slot value.
  • Samples with all varying numbers of words between the minimum and the maximum expected.

These samples should always include only slot values that represent actual phrases the user might say. Do not use meaningless placeholder words in the sample phrase just to fill the slot with the right number of words. Instead, fill the sample slot value with real-world examples of the data you want to collect in the slot.

If you are using the AMAZON.LITERAL type to collect free-form text with wide variations in the number of words that might be in the slot, note the following:

  • Covering this full range (minimum, maximum, and all in between) will require a very large set of samples. Try to provide several hundred samples or more to address all the variations in slot value words as noted above.
  • Keep the phrases within slots short enough that users can say the entire phrase without needing to pause.

Lengthy spoken input can lead to lower accuracy experiences, so avoid designing a spoken language interface that requires more than a few words for a slot value. A phrase that a user cannot speak without pausing is too long for a slot value.

For example, the intent for an ability that posts the user’s spoken words to a social media site might have an UpdateText slot that collects the text to post. Values for this slot range from just one word to about nine or ten words. The sample utterances to support this intent should cover a range of words such as the following:

StatusUpdate    post the update {arrived|UpdateText}
StatusUpdate    post the update {dinner time|UpdateText}
StatusUpdate    post the update {out at lunch|UpdateText}

...(more samples showing phrases with  4-10 words)

StatusUpdate    post the update {going to stop by the grocery store this evening|UpdateText}

This set includes sample slot values ranging from one word (“arrived”) to about ten words. This type of sample coverage should provide better recognition.

Built-in Intent Library Documentation

Navigate to all built-in intents in the Built-in Intent Library.

See all available slot types in the Slot Type Reference.

Learn more about using the built-in intent library:

Learn more about building your voice interface:

The built-in intent library incorporates material from Schema.org, which is licensed under the Creative Commons Attribution-ShareAlike License (version 3.0) (the “License”). You may not use this file except in compliance with the License. You may obtain a copy of the License at http://creativecommons.org/licenses/by-sa/3.0/. For questions, please reach out to alexa-ontology-support@amazon.com.