Implement the Built-in Intents

The Alexa Skills Kit provides a library of built-in intents. These are intents for common actions that you can choose to implement in your custom skill without providing any sample utterances.

Overview of the Built-in Intents

For example, the built-in AMAZON.HelpIntent is automatically mapped to common ways of requesting help from a skill. If you choose to use this intent, users can invoke your skill, say something like “help”, and the Alexa service sends your service an IntentRequest for the AMAZON.HelpIntent. Your service can handle this intent in a way appropriate for your skill.

Similarly, the built-in intent AMAZON.SearchAction<object@WeatherForecast> is automatically mapped to common ways of asking for the weather. If you implement this intent, users can say “what’s the weather in seattle” and the Alexa service sends your service an IntentRequest for AMAZON.SearchAction<object@WeatherForecast>, with a slot value for the city “Seattle.”

Using the built-in intents is useful for several reasons:

  • You do not need to spend the time writing sample utterances for the intent.
  • Users can use common, consistent phrases to access the intent across skills. This makes it easier for users to work with your skill.
  • Your skill gets the benefit of any future updates to the Alexa service that improve recognition and utterances for these intents.

The built-in intent library is organized in general categories:

For a complete reference to all available built in intents, see Built-in Intent Library.

Implementing a Built-in Intent

To implement a built-in intent, you need to add the intent to your intent schema, then add handling for the intent to your code.

When specifying the name of the intent, be sure to include the AMAZON namespace. For example, the following schema includes two custom intents and three built-in intents. You might use this set of built-ins in a skill that retrieves weather forecasts:

  • AMAZON.SearchAction<object@WeatherForecast>
  • AMAZON.HelpIntent
  • AMAZON.StopIntent
{
  "intents": [
    {
      "intent": "CustomIntentWithSlots",
      "slots": [
        {
          "name": "day",
          "type": "AMAZON.DATE"
        }
      ]
    },
    {
      "intent": "CustomIntent"
    },
    {
      "intent": "AMAZON.SearchAction<object@WeatherForecast>"
    },
    {
      "intent": "AMAZON.HelpIntent"
    },
    {
      "intent": "AMAZON.StopIntent"
    }
  ]
}

Add handling for each built-in intent to your code, the same way you handle custom intents. Be sure to include a handler for every intent in your schema. Examples of intent handlers:

If you are using the Alexa Skills Kit SDK for Node.js, you could code intent handlers like this:

var handlers = {
  'CustomIntent': function () {
      // Code for the custom GetLocationIntent goes here.
  },
  'CustomIntentWithSlots': function () {
      // Code for the custom GetLocationIntent goes here.
  },
  'AMAZON.SearchAction<object@WeatherForecast>': function () {        
      // Handler for the AMAZON.SearchAction<object@WeatherForecast> built-in intent.
  },
  'AMAZON.HelpIntent': function () {    
      // Code for the weather temperature handler goes here
  },
  'AMAZON.StopIntent': function () {
      // Code for the weather condition handler goes here.
  }
};

You could create handlers like this in Java:

@Override
public SpeechletResponse onIntent(final IntentRequest request, final Session session)
        throws SpeechletException {
    log.info("onIntent requestId={}, sessionId={}", request.getRequestId(),
            session.getSessionId());

    Intent intent = request.getIntent();
    String intentName = intent.getName();

    if ("CustomIntent".equals(intentName)) {
        // Handling for CustomIntent
    } else if ("CustomIntentWithSlots".equals(intentName)) {
        // Handling for CustomIntentWithSlots        
    } else if ("AMAZON.SearchAction<object@WeatherForecast>".equals(intentName)){
      // Handling for the built-in intent AMAZON.SearchAction<object@WeatherForecast>
    } else if ("AMAZON.HelpIntent".equals(intentName)) {
        // Handling for the built-in help intent goes here
    } else if ("AMAZON.StopIntent".equals(intentName)) {
        // Handling for the built-in stop intent goes here.
    } else {
        throw new SpeechletException("Invalid Intent");
    }
}

See Handling Requests Sent by Alexa for more about how to handle requests from the Alexa service.

Because users will request built-in intents using standard, common phrases, your service should handle the intent in a way consistent with the intended purpose. For instance, providing some other, non-help related functionality for the AMAZON.HelpIntent would confuse users who expect help when saying something like “help” or “what can you do?” If you include an intent such as AMAZON.SearchAction<object@WeatherForecast>, users can say phrases like “what’s the weather forecast,” so your intent handler should provide weather information.

See Built-in Intent Library to get the intended purpose and example utterances for the built-in intents.

When Not Using the Built-in Intents

Implementing the built-in intents is recommended, but optional. If you do not include a built-in intent in your intent schema, the Alexa service never sends that intent to your service, even if users say the phrases that would normally trigger the intent.

You can still map those phrases to your own custom intents in your sample utterances. For instance, you could create the intent MyHelpIntent and write sample utterances such as:

MyHelpIntent help
MyHelpIntent help me
MyHelpIntent what can I ask you
...

In this case, your service receives an IntentRequest for MyHelpIntent, even though these phrases overlap with the built-in AMAZON.HelpIntent.

This is not recommended, as the built-in intents typically provide better coverage than the sample utterances you would write manually. Instead, consider using the built-in intent, but extend it with additional skill-specific utterances.

Extending a Built-in Intent with Sample Utterances

You can extend the standard built-in intents by providing additional sample utterances. This is useful for invoking the intents with skill-specific utterances.

To extend the intent, map the phrases to it in your sample utterances, just as with your other intents. For example:

AMAZON.HelpIntent help me order a taxi
AMAZON.HelpIntent how do I order a taxi

In this case, the AMAZON.HelpIntent is invoked whenever the user:

  • Invokes your skill and says any of the standard requests for help (“help,” “help me,” and so on).
  • Invokes your skill and says one of these custom phrases (“help me order a taxi,” “how do I order a taxi?”).

Migrating to the Built-in Intents

Earlier versions of the Alexa Skills Kit did not provide these built-in intents, so you may have implemented your own versions of cancel, stop or help. Although these continue to work, you may want to migrate to the built-in intents to take advantage of improvements to the utterances over time.

To migrate your skill, do the following:

  1. Update your intent schema to replace the name of your custom intent with the name of the built-in intent.
  2. Remove the sample utterances for your custom intent, although you can keep any skill-specific utterances as noted in Extending a Built-in Intent with Sample Utterances.
  3. Update the intent handlers in your code with the name of the built-in intent.

Next Steps

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

Learn about the naming structure for the built-in intents: Understanding the Structure of the Built-in Intent Library

See all coding topics:

Other topics:

Reference materials: