Implement the Built-in Intents

The Alexa Skills Kit provides a library of built-in intents. You can use these intents in your custom skill without providing 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 don't need to spend the time writing sample utterances for the intent.
• Users can use common, consistent phrases to access the intent across skills. These common phrases make 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 has the following general categories:

• Standard intents – Intents that provide basic functionality, such as help, stop, cancel, and other actions. For details, see Standard Built-in Intents.
• Built-in intent library (developer preview) – Intents organized into categories, such as weather, local search, books and more. These intents automatically include slots and use a particular naming structure described in Understanding the Structure of the Built-in Intent Library.

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

Implement a built-in intent

To implement a built-in intent, add the intent to your intent schema, and then handle the intent in 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.CancelIntent
• AMAZON.HelpIntent
• AMAZON.StopIntent

The following example shows the intent schema with four built-in intents and a custom intent called WeatherOnThisDay.

{
  "interactionModel": {
    "languageModel": {
      "invocationName": "my weather",
      "intents": [
        {
          "name": "AMAZON.CancelIntent",
          "samples": []
        },
        {
          "name": "AMAZON.HelpIntent",
          "samples": []
        },
        {
          "name": "AMAZON.StopIntent",
          "samples": []
        },
        {
          "name": "AMAZON.SearchAction<object@WeatherForecast>",
          "samples": []
        },
        {
          "name": "WeatherOnThisDay",
          "slots": [
            {
              "name": "PastYear",
              "type": "AMAZON.FOUR_DIGIT_NUMBER"
            }
          ],
          "samples": [
            "what was the weather on this date in {PastYear}",
            "what was the weather in {PastYear}"
          ]
        }
      ],
      "types": []
    }
  }
}

See Interaction Model Schema for the complete intent schema compatible with the developer console and the Skill Management API.

Handle the built-in intents in your code, the same way you handle custom intents. Be sure to include a handler for every intent in your schema. The following code example shows intent handlers for an interaction model with four built-in intents and a custom intent.

• Node.js SDK v2
• Python SDK
• Java SDK v2

const WeatherOnThisDayHandler = {
    canHandle(handlerInput) {
        return Alexa.getRequestType(handlerInput.requestEnvelope) === 'IntentRequest'
            && Alexa.getIntentName(handlerInput.requestEnvelope) === 'WeatherOnThisDay';
    },
    handle(handlerInput) {
        const speakOutput = 'You invoked the Weather on this Day Intent.';

        return handlerInput.responseBuilder
            .speak(speakOutput)
            .reprompt(speakOutput)
            .getResponse();
    }
};

const WeatherForecastHandler = {
    canHandle(handlerInput) {
        return Alexa.getRequestType(handlerInput.requestEnvelope) === 'IntentRequest'
            && Alexa.getIntentName(handlerInput.requestEnvelope) === 'AMAZON.SearchAction<object@WeatherForecast>';
    },
    handle(handlerInput) {
        const speakOutput = 'You invoked the built-in weather forecast intent.';

        return handlerInput.responseBuilder
            .speak(speakOutput)
            .reprompt(speakOutput)
            .getResponse();
    }
};


const HelpIntentHandler = {
    canHandle(handlerInput) {
        return Alexa.getRequestType(handlerInput.requestEnvelope) === 'IntentRequest'
            && Alexa.getIntentName(handlerInput.requestEnvelope) === 'AMAZON.HelpIntent';
    },
    handle(handlerInput) {
        const speakOutput = 'You can ask me about the current weather, or historical weather on this day! How can I help?';

        return handlerInput.responseBuilder
            .speak(speakOutput)
            .reprompt(speakOutput)
            .getResponse();
    }
};


const CancelAndStopIntentHandler = {
    canHandle(handlerInput) {
        return Alexa.getRequestType(handlerInput.requestEnvelope) === 'IntentRequest'
            && (Alexa.getIntentName(handlerInput.requestEnvelope) === 'AMAZON.CancelIntent'
                || Alexa.getIntentName(handlerInput.requestEnvelope) === 'AMAZON.StopIntent');
    },
    handle(handlerInput) {
        const speakOutput = 'Goodbye!';

        return handlerInput.responseBuilder
            .speak(speakOutput)
            .getResponse();
    }
};

class WeatherOnThisDayHandler(AbstractRequestHandler):
    """Handler for WeatherOnThisDay Intent."""
    def can_handle(self, handler_input):
        # type: (HandlerInput) -> bool
        return ask_utils.is_intent_name("WeatherOnThisDay")(handler_input)

    def handle(self, handler_input):
        # type: (HandlerInput) -> Response

        # Logic for your handler goes here. This example just returns
        # a placeholder indicating the intent the user invoked

        speak_output = "You invoked the Weather on this Day Intent."

        return (
            handler_input.response_builder
                .speak(speak_output)
                # .ask("add a reprompt if you want to keep the session open for the user to respond")
                .response
        )

class WeatherForecastHandler(AbstractRequestHandler):
    """Handler for AMAZON.SearchAction<object@WeatherForecast> Intent."""
    def can_handle(self, handler_input):
        # type: (HandlerInput) -> bool
        return ask_utils.is_intent_name("AMAZON.SearchAction<object@WeatherForecast>")(handler_input)

    def handle(self, handler_input):
        # type: (HandlerInput) -> Response

        # Logic for your handler goes here. This example just returns
        # a placeholder indicating the intent the user invoked

        speak_output = "You invoked the built-in weather forecast intent."

        return (
            handler_input.response_builder
                .speak(speak_output)
                # .ask("add a reprompt if you want to keep the session open for the user to respond")
                .response
        )

class HelpIntentHandler(AbstractRequestHandler):
    """Handler for Help Intent."""
    def can_handle(self, handler_input):
        # type: (HandlerInput) -> bool
        return ask_utils.is_intent_name("AMAZON.HelpIntent")(handler_input)

    def handle(self, handler_input):
        # type: (HandlerInput) -> Response
        speak_output = "You can ask me about the current weather, or historical weather on this day! How can I help?"

        return (
            handler_input.response_builder
                .speak(speak_output)
                .ask(speak_output)
                .response
        )


class CancelOrStopIntentHandler(AbstractRequestHandler):
    """Single handler for Cancel and Stop Intent."""
    def can_handle(self, handler_input):
        # type: (HandlerInput) -> bool
        return (ask_utils.is_intent_name("AMAZON.CancelIntent")(handler_input) or
                ask_utils.is_intent_name("AMAZON.StopIntent")(handler_input))

    def handle(self, handler_input):
        # type: (HandlerInput) -> Response
        speak_output = "Goodbye!"

        return (
            handler_input.response_builder
                .speak(speak_output)
                .response
        )

// Each of these handlers is a separate Java class.

/**
 * *****************************************
 * WeatherOnThisDayHandler class
 * *****************************************
 */

package handlers;

import com.amazon.ask.dispatcher.request.handler.HandlerInput;
import com.amazon.ask.dispatcher.request.handler.RequestHandler;
import com.amazon.ask.model.Response;

import java.util.Optional;

import static com.amazon.ask.request.Predicates.intentName;

public class WeatherOnThisDayHandler implements RequestHandler {

    @Override
    public boolean canHandle(HandlerInput input) {
        return input.matches(intentName("WeatherOnThisDay"));
    }

    @Override
    public Optional<Response> handle(HandlerInput input) {

        // Logic for your handler goes here. This example just returns
        // a placeholder indicating the intent the user invoked

        String speechText = "You invoked the Weather on this Day Intent.";
        return input.getResponseBuilder().withSpeech(speechText).build();
    }

}

/**
 * *****************************************
 * WeatherForecastHandler class
 * *****************************************
 */

package handlers;

import com.amazon.ask.dispatcher.request.handler.HandlerInput;
import com.amazon.ask.dispatcher.request.handler.RequestHandler;
import com.amazon.ask.model.Response;

import java.util.Optional;

import static com.amazon.ask.request.Predicates.intentName;

public class WeatherForecastHandler implements RequestHandler {

    @Override
    public boolean canHandle(HandlerInput input) {
        return input.matches(intentName("AMAZON.SearchAction<object@WeatherForecast>"));
    }

    @Override
    public Optional<Response> handle(HandlerInput input) {

        // Logic for your handler goes here. This example just returns
        // a placeholder indicating the intent the user invoked

        String speechText = "You invoked the built-in weather forecast intent.";
        return input.getResponseBuilder().withSpeech(speechText).build();
    }

}

/**
 * *****************************************
 * HelpIntentHandler class
 * *****************************************
 */

package handlers;

import com.amazon.ask.dispatcher.request.handler.HandlerInput;
import com.amazon.ask.dispatcher.request.handler.RequestHandler;
import com.amazon.ask.model.Response;

import java.util.Optional;

import static com.amazon.ask.request.Predicates.intentName;

public class HelpIntentHandler implements RequestHandler {

    @Override
    public boolean canHandle(HandlerInput input) {
        return input.matches(intentName("AMAZON.HelpIntent"));
    }

    @Override
    public Optional<Response> handle(HandlerInput input) {
        String speechText = "You can ask me about the current weather, or historical weather on this day! How can I help?";
        return input.getResponseBuilder()
                .withSpeech(speechText)
                .withSimpleCard("HelloWorld", speechText)
                .withReprompt(speechText)
                .build();
    }
}

/**
 * *****************************************
 * CancelandStopIntentHandler class
 * *****************************************
 */

package handlers;

import com.amazon.ask.dispatcher.request.handler.HandlerInput;
import com.amazon.ask.dispatcher.request.handler.RequestHandler;
import com.amazon.ask.model.Response;

import java.util.Optional;

import static com.amazon.ask.request.Predicates.intentName;

public class CancelandStopIntentHandler implements RequestHandler {
    @Override
    public boolean canHandle(HandlerInput input) {
        return input.matches(intentName("AMAZON.StopIntent").or(intentName("AMAZON.CancelIntent")));
    }

    @Override
    public Optional<Response> handle(HandlerInput input) {
        String speechText = "Goodbye";
        return input.getResponseBuilder()
                .withSpeech(speechText)
                .withSimpleCard("HelloWorld", speechText)
                .build();
    }
}

For details about how to handle requests from the Alexa service, see Handling Requests Sent by Alexa.

Users say standard, common phrases to request the built-in intents. Therefore, your service should handle the intent in a way consistent with the intended purpose. For example, providing some other, non-help related functionality for the AMAZON.HelpIntent would confuse users who expect help when they say words like "help" or "what can you do?" If you include the AMAZON.SearchAction<object@WeatherForecast> intent, users can say phrases like "what's the weather forecast," so your intent handler should provide weather information.

To determine the intended purpose and example utterances for a built-in intent, see Built-in Intent Library and Standard Built-in Intents.

Using custom intents instead of the built-in intents

You must implement the required intents, such as AMAZON.StopIntent. Implementing the other built-in intents is recommended, but optional. If you don't 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 for the built-in 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 the following sample utterances:

help
help me
what can I ask you

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

This approach isn't recommended because the built-in intents provide better coverage than the sample utterances you write manually. Instead, use the built-in intent and extend it with skill-specific utterances.

Extend a built-in intent with sample utterances

You can extend the standard built-in intents by providing additional sample utterances. Extending a built-in intent is useful when you want to provide skill-specific utterances.

To extend a built-in 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 Add next to Custom > Interaction Model > Intents.
4. Select Use an existing intent from Alexa's built-in library.
5. Find the built-in intent to add and click Add Intent.
6. After adding the intent, select it in the left-hand navigation, and then enter the Sample Utterances.

The following example shows the JSON interaction model for an extended built-in intent.

{
  "name": "AMAZON.HelpIntent",
  "slots": [],
  "samples": [
    "how do i order a taxi",
    "help me order a taxi"
  ]
}

See Interaction Model Schema for the complete intent schema compatible with the developer console and the Skill Management API.

In this example, Alexa sends your skill the AMAZON.HelpIntent intent whenever the user does either of the following:

• 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?").

Migrate to the built-in intents

Earlier versions of the Alexa Skills Kit didn't provide these built-in intents. You might have implemented your own versions of cancel, stop, or help. Although these custom intents continue to work, migrate to the built-in intents to take advantage of improvements to the utterances over time.

To migrate your skill to the built-in intents

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 Extend a Built-in Intent with Sample Utterances.
3. Update the intent handlers in your code with the name of the built-in intent.

Related topics

• Built-in Intent Library
• Understanding the Structure of the Built-in Intent Library
• Tips for Using Built-in Intents for Your Skill

Learn more about intents and the interaction model:

• Create Intents, Utterances, and Slots
• Interaction Model Schema

Learn about coding the service for your skill: Handling Requests Sent by Alexa.

Last updated: Nov 28, 2023