Create Intents, Utterances, and Slots

To create your custom interaction model, you create the intents, slots, and sample utterances for your skill. An intent represents an action that fulfills a user's spoken request. Intents can optionally have arguments called slots. The sample utterances are set of likely spoken phrases mapped to the intents.

For details and code examples that show how you access intents and slots sent in user requests during skill runtime, see Handle Requests Sent by Alexa.

Create a new custom intent

When you create a new custom intent, you provide a name and a list of utterances that users would say to invoke this intent. You can start by just writing out the full phrases, and then identify the slots within the phrases later.

For example, for an intent to plan a trip (PlanMyTrip), you might write the following utterances:

i am going on a trip on friday
i want to visit portland
i want to travel from seattle to portland next friday
i'm driving from seattle to portland
i'm driving to portland to go hiking
...(several more)

For recommendations for writing good sample utterances, see:

For limits on the number of intents you can create in a single skill, see Interaction model limits.

To create a new custom intent

  1. Open the Alexa developer console, and then sign in.
  2. On the Skills tab, in the SKILL NAME column, click the name of your custom skill.
  3. From the left-hand sidebar, click Custom > Interaction Model > Intents.
  4. On the Intents page, click +Add Intent.
  5. Enter the name of the new intent, and then click Create custom intent.

    This action adds a new intent and opens its detail page, displaying the intent's sample utterances and slots.

    For details about how you can name a custom intent, see Intent and slot name requirements.

  6. Enter a sample utterance in the edit box, and then click the plus sign (+) or press Enter. Repeat this for a few representative utterances.

    • Be sure to include utterances that include words and phrases that will vary when users say the intent. In the previous example, this includes words and phrases like "friday," "san francisco", "seattle," and "next thursday."
    • Sample utterances must be unique. You can't have duplicate sample utterances mapped to different intents.
  7. Identify the slots in the utterances as described in Identify the slots for the intent.
Built-in Library

The Alexa Skills Kit includes a large library of built-in intents you can use instead of creating your own. You don't need to write the utterances for these intents, thus simplifying development.

You can search the full built-in intent library from within the developer console. Create a new intent as described previously, but select the Use an existing intent from Alexa's built-in library option. Click +Add Intent for each built-in intent to add.

Rules for sample utterances

Follow these rules when you write your sample utterances:

  • Write out numbers as words and not digits ("five", not "5").
  • Separate acronyms and other phrases involving spoken letters by periods and spaces ("n. b. a.", not "nba").
  • Leave out punctuation marks in most cases ("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.
  • Spell words with umlauts (ä, ü, ö) and a sharp S (ß) correctly. For example, use "büro" not "buero", and "fußball" not "fussball".
  • If the word for a slot value might have apostrophes indicating the possessive, or any other similar punctuation (such as periods or hyphens) include those within the brackets defining the slot. Don't 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.
      • Don't use: "tell me a {Drink}'s ingredients" in the sample utterance.
    • For hyphenated values:
      • Use: editor-in-chief in the custom values and {Position} in the sample utterance.
      • Don't use: editor in the custom values and {Position}-in-chief in the sample utterance.
  • Write utterances in the language for the skill. For example, for the German version of your interaction model, write the sample utterances in German.

As you test, you will likely add additional sample utterances. After you add a new utterance, there might be a short delay before the new utterance is available for testing, particularly if you want to test the utterance with your invocation name ("Alexa, ask <invocation name> to give me the horoscope for Gemini").

Identify the slots for the intent

After you write a few utterances, notice the words or phrases that represent variable information. These words and phrases become the intent's slots. For example, in the utterances identified earlier, the variables are highlighted in red.

i am going on a trip on friday
i want to visit portland
i want to travel from seattle to portland next friday
i'm driving from seattle to portland
i'm driving to portland to go hiking

Create a slot for each of these words or phrases and then replace the original word with the slot name in curly brackets ({ }).

To create a slot

  1. Open the Alexa developer console, and then sign in.
  2. On the Skills tab, in the SKILL NAME column, click the name of your custom skill.
  3. From the left-hand sidebar, click Custom > Interaction Model > Intents.
  4. Click an intent to open the detail page for the intent.
  5. In an utterance, drag your cursor over the word or phrase representing the slot value to highlight it.
  6. In the drop-down box, enter a name for the slot in the edit box, and then click Add.

    This action creates a new slot for the intent and replaces the original value in the utterance with the slot name in curly brackets ({ }).

    For the example shown earlier, the word "seattle" represents the city the user wants to depart from, so you might call this slot fromCity. After you define the fromCity slot, the utterance looks like the following example.

    i want to travel from {fromCity} to portland next friday

    For details about how you can name slots, see Intent and slot name requirements.

  7. Repeat these steps for all the remaining variable words.

    In the PlanMyTrip intent, you might end up with the slots like this:

    • fromCity
    • toCity
    • travelDate
    • travelMode
    • activity

On the Intents detail page, the Intent Slots section after the Sample Utterances section displays the slots you add. When you highlight a word or phrase in an utterance, you can add a new slot or select an existing slot.

For example, the set of utterances shown earlier now looks like the following example.

i am going on a trip on {travelDate} 
i want to visit {toCity} 
I want to travel from {fromCity} to {toCity} {travelDate} 
I'm {travelMode} from {fromCity} to {toCity}
i'm {travelMode} to {toCity} to go {activity}

Assign slot types to your slots

Every slot has a slot type that determines how Alexa handles the user input and passes the value on to your skill. You can assign slot types from the detail page for an intent or the slot detail page for the slot. When assigning slot types, you can:

  • Use a built-in slot type. The built-in types include types for converting data such as dates, and types that provide recognition for commonly used lists of values, such as large cities. You can extend some of these types with additional values as well.
  • Create a custom slot type. In this case, you provide the slot type name and a list of custom values.

To assign a slot type to a slot

  1. Open the Alexa developer console, and then sign in.
  2. On the Skills tab, in the SKILL NAME column, click the name of your custom skill.
  3. From the left-hand sidebar, click Custom > Interaction Model > Intents.
  4. Click an intent to open the detail page for the intent.
  5. After the Sample Utterances section, in the Intent Slots section, click the Select a slot type menu.
  6. To use an existing custom slot type or one of the built-in types, select the type from the list.
  7. To create a new custom slot type, see Create and Edit Custom Slot Types.
  8. To save the slot type changes, click Save Model.

Configure a slot for multiple values

Use a multiple-value slot to collect multiple values from a user utterance into single slot. For example, a multiple-value slot called {toppings} could work with an utterance such as "I want a pizza with pepperoni, mushrooms, and olives". This utterance sends your skill an array with three values in a single {toppings} slot. This lets the user provide multiple values in a more natural utterance.

To configure the slot for multiple values

  1. Open the Alexa developer console, and then sign in.
  2. On the Skills tab, in the SKILL NAME column, click the name of your custom skill.
  3. From the left-hand sidebar, click Custom > Interaction Model > Intents.
  4. Click an intent to open the detail page for the intent.
  5. In the list of Intent Slots, find the slot to change.

    The MULTI-VALUE column shows whether this slot can collect multiple values.

  6. Click the slot to open the slot detail page.
  7. Under Multi-Value, select the Can this slot contain multiple values? option.

For details about multiple-value slots, see Collect Multiple Values in a Slot

Edit or upload sample utterances in bulk

Use bulk edit to quickly upload or edit your sample utterances. When you edit in bulk, include slots in the utterances manually with curly brackets.

To bulk edit or import utterances

  1. Open the Alexa developer console, and then sign in.
  2. On the Skills tab, in the SKILL NAME column, click the name of your custom skill.
  3. From the left-hand sidebar, click Custom > Interaction Model > Intents.
  4. Click an intent to open the detail page for the intent.

  5. In the upper-right corner of the Sample Utterances section, click Bulk Edit.
  6. Either edit the sample utterances in the edit box, or drag a CSV file to the window to import the contents.

    • Enter one utterance per line.
    • When you import a CSV file, the new file replaces the existing utterances shown in the edit box.
    • Select the The CSV below contains headers check box to omit the top line shown in the text field.
    • Your changes to the utterances aren't saved until you click Submit.
  7. Click Submit.

JSON for intents and utterances (interaction model schema)

You can review and edit the JSON representation of all of your intents and utterances in the JSON Editor. The interactionModel.languageModel.intents property contains an array of intent objects. For a given intent, the samples property contains an array of sample utterances. If the intent has any slots, the slots property contains an array of slot objects. A slot object can also have a samples property if you have defined user utterances for the slot as part of the dialog model.

The following example shows a portion of the intent object for a PlanMyTrip intent. The utterances for the intent are in interactionModel.languageModel.intents[].samples. Each slot has its own samples array. For brevity, other properties within interactionModel and languageModel are not shown. For details about the interaction model JSON, see Interaction Model Schema.

{
  "interactionModel": {
    "languageModel": {
      "intents": [
        {
          "name": "PlanMyTrip",
          "slots": [
            {
              "name": "travelDate",
              "type": "AMAZON.DATE",
              "samples": [
                "I am taking this trip on {travelDate}",
                "on {travelDate}",
                "{travelDate}"
              ]
            },
            {
              "name": "toCity",
              "type": "AMAZON.US_CITY",
              "samples": [
                "I'm going to {toCity}",
                "{toCity}"
              ]
            },
            {
              "name": "fromCity",
              "type": "AMAZON.US_CITY",
              "samples": [
                "{fromCity}",
                "I'm starting from {fromCity}"
              ]
            },
            {
              "name": "travelMode",
              "type": "LIST_OF_TRAVEL_MODES",
              "samples": [
                "I am going to {travelMode}",
                "{travelMode}"
              ]
            },
            {
              "name": "activity",
              "type": "LIST_OF_ACTIVITIES",
              "samples": [
                "{activity}",
                "I plan to {activity}"
              ]
            }
          ],
          "samples": [
            "{toCity}",
            "I want to travel from {fromCity} to {toCity} {travelDate}",
            "i want to visit {toCity}",
            "i am going on trip on {travelDate}",
            "I'm {travelMode} from {fromCity} to {toCity}",
            "i'm {travelMode} to {toCity} to {activity}",
            "plan a trip",
            "plan a trip to {toCity} ",
            "plan a trip starting from {fromCity} ",
            "I'd like to leave on {travelDate} ",
            "I'd like to leave on the {travelDate} ",
            "I'd like to fly out of {fromCity} "
          ]
        }
      ]
    }
  }
}