Home > Alexa > Alexa Skills Kit

Understanding the Structure of the Built-in Intent Library

Intro

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": [
    {
      "intent": "AMAZON.SearchAction<object@WeatherForecast>"
    }
  ]
}

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 Creating 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?

Identifying the parts of an utterance
Identifying the parts of an utterance
  • 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:

Mapping the utterance parts to actions, entity types, and properties
Mapping the utterance parts 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.

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

Understanding 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:

Combining actions and properties into an intent signature
Combining actions and properties 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.

Using 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": [
    {
      "intent": "AMAZON.SearchAction<object@WeatherForecast>"
    },
    {
      "intent": "HelloWorldIntent"
    },
    {
      "intent": "AnotherCustomIntent"
    }
  ]
}

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 readability):

{
  "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).

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.

Referencing property values via the SearchAction.object property
Referencing property values via the SearchAction.object property

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"
        }
      }
    }
  }
}
Passing property values as slots
Passing property values as slots

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

Scoping 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": [
    {
      "intent": "AMAZON.SearchAction<object@WeatherForecast>"
    },
    {
      "intent": "AMAZON.SearchAction<object@WeatherForecast[temperature]>"
    },
    {
      "intent": "AMAZON.SearchAction<object@WeatherForecast[weatherCondition]>"
    },
    {
      "intent": "CustomIntent"
    }
  ]
}

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: Creating 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.

{
  "intents": [
    {
      "intent": "AMAZON.SearchAction<object@WeatherForecast>"
    },
    {
      "intent": "AMAZON.SearchAction<object@WeatherForecast[temperature]>"
    },
    {
      "intent": "AMAZON.SearchAction<object@WeatherForecast[weatherCondition]>"
    },
    {
      "intent": "GetLocationIntent",
      "slots": [
        {
          "name": "City",
          "type": "AMAZON.US_City"
        }
      ]
    }
  ]
}

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:

User: Alexa, ask My Weather what’s the weather today?
Alexa sends the skill the AMAZON.SearchAction<> object@WeatherForecast> with today’s date as the slot value for object.startDate. Note that the user did not specify a location, so the three object.location slots are empty.
My Weather: For what location?
Skill keeps session open to get the user’s reply.
User: Seattle
Alexa sends the skill the custom GetLocationIntent with ‘Seattle’ as the slot value for City. The skill now has enough information to complete the original WeatherForecast request.
Alexa: Light rain this afternoon through tomorrow, with temperatures falling to 56°F on Monday.

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:

GetLocationIntent {City}
GetLocationIntent in {City}
GetLocationIntent 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.

Intent Name Intent Handler Tasks

AMAZON.SearchAction<object@WeatherForecast>

Responds with a general weather forecast:

  • Get the location and date from the slots (object.location.addressLocality.name, object.location.addressRegion.name, object.location.addressCountry.name, object.startDate).
  • Validate inputs and do any conversions as need.
  • Call a weather service to look up the weather.
  • Use the weather data to 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, the handler saves any existing data in the session and returns a response asking the user for a location.

AMAZON.SearchAction<object@WeatherForecast[temperature]>

Responds with the high and low temperature:

  • Get the location and date from the slots (object.location.addressLocality.name, object.location.addressRegion.name, object.location.addressCountry.name, object.startDate).
  • Validate inputs and do any conversions as need.
  • Call a weather service to look up the weather.
  • Use the weather data to construct a specific response telling the user just the high and low temperature: “Today’s high is 65 degrees, and the low will be 50 degrees.”

If the location slots are empty, the handler saves any existing data in the session and returns a response asking the user for a location.

AMAZON.SearchAction<object@WeatherForecast[weatherCondition]>

Responds with details about a particular weather condition, such as rain or snow:

  • Get the location and date from the slots (object.location.addressLocality.name, object.location.addressRegion.name, object.location.addressCountry.name, object.startDate).
  • Also get the value of the object.weatherCondition.name slot. This tells you the specific weather condition the user asked about.
  • Validate inputs and do any conversions as need.
  • Call a weather service to look up the weather.
  • Use the weather data to construct a specific response about the particular weather condition: “Light rain is expected to start this afternoon and continue until evening.”

If the location slots are empty, the handler saves any existing data in the session and returns a response asking the user for a location.

GetLocationIntent

This custom intent is meant to capture missing location information and then respond with any of the three types of forecasts provided by the other handlers (general, temperature, or weather condition):

  • Get the previously-provided data from the session attributes.
  • Get the data from the City slot.
  • Validate inputs and do any conversions as needed.
  • Call a weather service to look up the weather.
  • Use the weather data to construct a specific response based on the initial intent the user invoked (general, temperature, or weather condition).

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.

Next Steps

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

Learn more about creating an intent schema:

Other coding topics:

Other topics:

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.