Understand the Structure of the Built-in Intent Library

• Introduction to the Built-in Library
  • Get Started
• Actions, Entity Types, and Properties
• Understand the Intent Signature
  • Actions with Multiple Properties
  • Use the Intent Signature in the Intent Schema
• Property Values Passed as Slot Values
  • Property Types and Slots
• Scope an Intent with a Property Name
• Example: A Weather Skill with the WeatherForecast Intents
  • Intent Schema for the Weather Skill
  • Intent Handlers for the Weather Skill
• Related Topics

Introduction to the Built-in Library

The built-in intent library gives you access to built-in intents that fall into categories, such as weather forecasts and local business searches. You can use these intents to add functionality to your skill without providing any sample utterances.

Using one of these in your skill is similar to using a standard built-in intent like AMAZON.HelpIntent:

1. Add the intent name to your intent schema.
2. Implement a handler for the intent in your code.

The differences are:

• Intents in the library are named according to a structure using actions, entity types, and properties (described in more detail below). Understanding this naming convention can help you understand the purpose and use of each intent.
• Intents in the library also have slots for providing additional information from the user's utterance. The slots are provided automatically, based on the entity types used within the intent definition. This means you do not define them in the intent schema. In contrast, the standard built-in intents like AMAZON.HelpIntent cannot use slots.

For example, an intent for a weather forecast looks like this in an intent schema:

{
  "intents": [
    {
      "name": "AMAZON.SearchAction<object@WeatherForecast>",
      "samples": []
    }
  ]
}

For brevity, most JSON examples in this document show just the intent definitions within the intents array and not the rest of the schema. See Interaction Model Schema for the complete intent schema compatible with the developer console and the Skill Management API.

Although no slots are defined in the above schema, an utterance like "what's the weather today in Seattle" would send your skill a request with slots containing today's date and the city "Seattle."

These intents are assembled from a set of actions, entity types, and properties. The name of each intent combines these elements into an intent signature (for instance, AMAZON.SearchAction<object@WeatherForecast>). You use this signature as the intent name.

Get Started

To see the full set of intents you can use in your skill, go to Built-in Intent Library.

To see a sample intent schema for a simple weather forecast skill, see Example: A Weather Skill with the WeatherForecast Intents, below.

If you want to understand the actions, entity types, and properties used in the naming structure for the intents, continue with the sections below.

Actions, Entity Types, and Properties

Although you can use the built-in intents just by adding the intent signatures to your intent schema, it may be helpful to understand the structure of the intent signature.

The intents in the built-in intent library are defined by a set of actions, entity types, and properties. Similar to a programming language, the actions and entity types are classes that have properties. An intent signature assembles these building blocks into a name that you can use in your intent schema.

An action represents an action the user is trying to take, such as searching for information. For instance, SearchAction represents the "searching for information" action. An intent defined with SearchAction indicates that the user wants search or look up information, such as finding a weather forecast or finding the phone number for a nearby coffee shop. An intent defined with AddAction indicates that the user wants to add information somewhere, such as adding an event to a calendar or adding the title a book to a reading list.

Most actions operate on other objects or use other objects. A search action needs to identify the information to search for. An add action needs to identify the item to add and possibly also the list to which to add it. These items are specified using the properties of the action. For example, SearchAction has an object property that identifies the type of information the user wants to find. AddAction has a targetCollection property to identify the type of the target list and an object property to identify the type object to add to the list.

An entity type represents the objects that the actions can act on or use. Entity types also have attributes, which are represented by properties. For example, WeatherForecast is an entity type that defines a weather forecast. It has properties such as location, duration, and temperature (among others).

Consider the utterance "what is the weather in Seattle today?"

• The entire utterance indicates that the user wants to search for something or find information.
• The "object" of the search – the information the user wants to find – is a weather forecast. This is the main focus or purpose in the sentence.
• The words "Seattle" and "today" are attributes of the weather forecast the user wants to find.

These parts of the utterance map to actions, entity types, and properties:

• The SearchAction action represents the user's intent to search for information.

• The object property of SearchAction represents the entity type to find.

  Note: The object property is named 'object' because it generally represents the grammatical object of the sentence the user states.
• The WeatherForecast entity type represents a weather forecast.
• The WeatherForecast entity type has properties that represent possible attributes of a weather forecast, such as the location and date (location and startDate).

The above items form the intent signature.

Understand the Intent Signature

An intent signature starts with the action and sets the type of the action's properties to the entity types it acts on or uses with the following syntax:

AMAZON.Action<propertyName@EntityType,propertyName@EntityType>

For example, to define an intent for asking about weather, the action is SearchAction, its property is object, and the entity type is WeatherForecast:

AMAZON.SearchAction<object@WeatherForecast>

The @ sign in this context declares that the object property is of the type WeatherForecast. You could read the full intent signature as:

"Search for Weather Forecast."

Continuing the earlier example "what is the weather in Seattle today?", here are the actions, entity types, and properties combined into an intent signature:

Actions with Multiple Properties

As noted above, an action can have multiple properties. For example:

AMAZON.AddAction<object@Book,targetCollection@ReadingList>

Again, the @ sign in this context declares the type of the specified properties object (Book) and targetCollection (ReadingList). You could read this intent signature as:

Add Book to Reading List.

Use the Intent Signature in the Intent Schema

The intent signature corresponds to the intent name you use in your intent schema. Include the full signature:

{
  "intents": [
    {
      "name": "AMAZON.SearchAction<object@WeatherForecast>",
      "samples": []
    }
  ]
}

With this defined in your intent schema, a user utterance such as "what's the weather" sends your skill AMAZON.SearchAction<object@WeatherForecast> as the intent (full set of request properties and empty slots not shown for brevity):

{
  "request": {
    "type": "IntentRequest",
    "intent": {
      "name": "AMAZON.SearchAction<object@WeatherForecast>",
      "slots": {}
    }
  },
}

For the list of valid intent signatures you can use, see the Built-in Intent Library reference. This reference is organized by high-level category (such as Books, Local Search, and Weather) and then by the entity types used within intent signatures (such as Book, LocalBusiness, or WeatherForecast).

You can also search the library of built-in intents when you add an intent in the developer console.

Property Values Passed as Slot Values

Entity types such as WeatherForecast have their own properties that further define its attributes, such as startDate, location and duration. When users say utterances that invoke an intent defined with WeatherForecast, they may mention values that correspond to these attributes, such as the date and location of the weather forecast they want. These property values are conveyed to your skill as slots.

Unlike with custom intents, you do not declare these slots in your intent schema. Alexa recognizes the slots from the properties of the objects included in the intent signature. If the user mentions any possible values for those slots, those values are provided in the request as slot values. The property name is used as the slot name.

For example, in the utterance "what is the weather today," the word "today" corresponds to a possible value for the WeatherForecast.startDate property. Assuming you have AMAZON.SearchAction<object@WeatherForecast> in your intent schema, this utterance sends your skill this request (shortened for readability):

{
  "request": {
    "type": "IntentRequest",
    "intent": {
      "name": "AMAZON.SearchAction<object@WeatherForecast>",
      "slots": {
        "object.startDate": {
          "name": "object.startDate",
          "value": "2016-11-01"
        }
      }
    }
  }
}

Note that the slot name is object.startDate. This is because of the structure of the intent signature noted earlier:

• The SearchAction.object property has been declared as the type WeatherForecast.
• startDate is a property of WeatherForecast, which means it is now a property of object.

You can think of the fully-qualified path to the startDate property as SearchAction.object.startDate. This is shortened in the JSON to just object.startDate since SearchAction in the intent signature defines the context.

Property Types and Slots

The properties of entity types have their own types. For some properties, the property type represents information that can map directly to an AMAZON slot type. For example:

• WeatherForecast.startDate: A date. This property maps to the AMAZON.DATE slot type to convert words like "today" into a date format like "2016-11-01".
• WeatherForecast.duration: A duration like "4 days." This property maps to the AMAZON.DURATION slot type that converts words representing durations into an ISO-formatted duration like "P4D".

Some properties are themselves objects with their own properties, and it is these that map to slot types. For example, the location property of WeatherForecast has multiple properties that map to slot types:

• WeatherForecast.location.addressLocality.name: A city (AMAZON.US_CITY).
• WeatherForecast.location.addressRegion.name: a region, such as a US state (AMAZON.US_STATE).
• WeatherForecast.location.addressCountry.name: a country name (AMAZON.Country).

The utterance "what is the weather in Seattle today" sends this request to the skill:

{
  "request": {
    "type": "IntentRequest",
    "intent": {
      "name": "AMAZON.SearchAction<object@WeatherForecast>",
      "slots": {
        "object.startDate": {
          "name": "object.startDate",
          "value": "2016-11-01"
        },
        "object.location.addressLocality.name": {
          "name": "object.location.addressLocality.name",
          "value": "Seattle"
        }
      }
    }
  }
}

The references for the available intents include the list of slots your skill can expect.

Scope an Intent with a Property Name

You may want to define intents that represent more specific questions. For example, a weather skill can respond to generic requests for the forecast ("what is the weather"), but you might want to know when users ask more specific questions about the weather. For instance, you might want your skill to handle these utterances differently:

1. "What is the weather in Seattle today?" (respond with a general weather forecast).
2. "What is the temperature in Seattle today?" (respond with just the current temperature and expected high).
3. "When will it rain next in Seattle?" (respond with just the likelihood of precipitation).

In the second utterance, the user referred to the temperature property of the WeatherForecast entity type. In the third, the user referenced the weatherCondition property by mentioning "rain."

You can use an intent signature that defines more specific intents with this syntax:

Action<propertyName@EntityType[propertyName]>

For example, if you put the intent signature SearchAction<object@WeatherForecast[temperature] in your intent schema, Alexa invokes this intent for weather-related utterances that refer to the temperature property. More generic weather utterances that do not refer to this property do not trigger the intent.

For example, note this schema:

{
  "intents": [
    {
      "name": "AMAZON.SearchAction<object@WeatherForecast>",
      "samples": []
    },
    {
      "name": "AMAZON.SearchAction<object@WeatherForecast[temperature]>",
      "samples": []
    },
    {
      "name": "AMAZON.SearchAction<object@WeatherForecast[weatherCondition]>",
      "samples": []
    }
  ]
}

These utterances invoke the intents:

• "What's the weather today in Seattle": Sends AMAZON.SearchAction<object@WeatherForecast> with the slots object.startDate and object.location.addressLocality.name.
• "What's the high temperature in Seattle today": Sends AMAZON.SearchAction<object@WeatherForecast[temperature]> with the slots object.startDate, object.location.addressLocality.name, and object.temperature.type.
• "When will it rain in Seattle": Invokes AMAZON.SearchAction<object@WeatherForecast[weatherCondition]> with the slots object.location.addressLocality.name and object.weatherCondition.

See the available intents to see the full set of intents available for each entity type.

Example: A Weather Skill with the WeatherForecast Intents

The following example illustrates how you might put all of these intents together to create a simple weather skill. Suppose you wanted to create a skill that responds to weather-related questions. For example, the skill might support interactions like the following:

1. A general request for the weather:

   User: Alexa, ask My Weather what's the weather in Seattle today?
   

   My Weather: Light rain this afternoon through tomorrow, with temperatures falling to 56 degrees on Monday.
   

2. A request for the expected temperature:

   User: Alexa, ask My Weather what will the high temperature be in Seattle today?
   

   My Weather: Today, expect a high of 65 degrees, and a low of 49.
   

3. A question about a particular weather condition:

   User: Alexa, ask My Weather when will it rain next in Seattle?
   

   My Weather: Light rain is expected to start this afternoon, continuing until evening.
   

4. A request for the weather that doesn't include all of the information needed:

   User: Alexa, ask My Weather what's the weather today?
   

   My Weather: For what location?
   User: Seattle
   

   Alexa: Light rain this afternoon through tomorrow, with temperatures falling to 56 degrees on Monday.
   

Note that the slightly different context of each question elicits a different response from the skill.

For all of these questions, the skill needs a location and a date, although the date could be defaulted to today's date if not provided.

Intent Schema for the Weather Skill

The following example shows a possible intent schema for a weather skill. Note that it includes three built-in WeatherForecast Intents. These are specified with just the intent name, since the slots are recognized automatically. The schema also includes a custom intent for capturing utterances not covered by the built-in intents. This intent has a normal slot definition.

{
  "interactionModel": {
    "languageModel": {
      "invocationName": "my weather",
      "intents": [
        {
          "name": "AMAZON.SearchAction<object@WeatherForecast>",
          "samples": []
        },
        {
          "name": "AMAZON.SearchAction<object@WeatherForecast[temperature]>",
          "samples": []
        },
        {
          "name": "AMAZON.SearchAction<object@WeatherForecast[weatherCondition]>",
          "samples": []
        },
        {
          "name": "GetLocation",
          "slots": [
            {
              "name": "City",
              "type": "AMAZON.US_CITY"
            }
          ],
          "samples": [
            "{City}",
            "give me the weather for {City}",
            "I'm in {City}",
            "I want information for {City}",
            "in {City}",
            "for {City}"
          ]
        }
      ],
      "types": []
    }
  }
}

The only sample utterances you need to provide would be for any custom intents you include, such as GetLocationIntent shown above. In this example, this intent gets the user's response if they do not include the desired location in the initial request:

To keep it simple, this example uses GetLocationIntent to just collect a city for the forecast. Alternatively, you could add slots for the region and country, similar to what the built-in intents provide. These sample utterances for GetLocationIntent would work in the above example:

{City}
give me the weather for {City}
I'm in {City}
I want information for {City}
in {City}
for {City
... (many more)

Intent Handlers for the Weather Skill

Based on the example intent schema, your code needs four intent handlers – one for each of the three built-ins, and one for the custom intent. Each handler gathers the information it needs from the intent and creates an appropriate response.

If you are using the Alexa Skills Kit SDK for Node.js to write the code for your skill, you could set up your intent handlers like this:

var weatherHandlers = {
    'AMAZON.SearchAction<object@WeatherForecast>': function () {        
        // Get the location and date slot values from the IntentRequest. 
        // Note syntax for getting JSON values with a dot (.) character in the name.

        var startDateSlotValue = this.event.request.intent.slots["object.startDate"].value;
        var cityLocationValue = this.event.request.intent.slots["object.location.addressLocality.name"].value;

        // Validate the inputs and do any conversions as needed.
        // Call the API for a weather service to lookup the weather
        // Construct a general response with the high and low temperature, chance 
        // of precipitation, and comments around sun or clouds.
        // If the location slots are empty, save any existing data in the session 
        // and return a response asking the user for a location.
        
        var output = "String with the weather output.";
        this.emit(':tellWithCard', output, "Weather", output);        
    },
    'AMAZON.SearchAction<object@WeatherForecast[temperature]>': function () {    
        // Code for the weather temperature handler goes here

        var output = "String with the weather forecast, explaining expected temperatures.";
        this.emit(':tellWithCard', output, "Weather - Temperature", output);
    },
    'AMAZON.SearchAction<object@WeatherForecast[weatherCondition]>': function () {
        // Code for the weather condition handler goes here. The weather condition
        // the user asked about is in the 'object.weatherCondition.name' slot.
        
        var weatherCondition = this.event.request.intent.slots["object.weatherCondition.name"].value;

        var output = "String with the weather forecast, with details around the specified weather condition."
        this.emit(':tellWithCard', output, "Weather - Weather Condition", output);            
    },
    'GetLocationIntent': function () {
        // Code for the custom GetLocationIntent goes here. 
    }
};

See Alexa Skills Kit SDK for Node.js for details about how to use the SDK.

Related Topics

See all of the available built-in intents: Built-in Intent Library

Learn more about creating intents and the interaction model:

• Choose the Invocation Name for a Custom Skill
• Create the Interaction Model for Your Skill
• Best Practices for Sample Utterances and Custom Slot Type Values
• Interaction Model Schema
• Alexa Design Guide

Other topics:

• Handling Requests Sent by Alexa
• Implementing the Built-in Intents
• Steps to Build a Custom Skill

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 contact us.

Last updated: Nov 28, 2023