Voice Design Handbook (Legacy)

This document provides a quick overview of what the Alexa Skills Kit supports for custom skills, so you can quickly create new experiences for Alexa. This section provides an overview to enable you to get up and running quickly. See the new Alexa Design Guide for stylistic recommendations and some best practices in voice user interface (VUI) design to maximize usability and drive high adoption of your Alexa skill.

Overview

To create successful, satisfying customer experiences, take a simple approach in which the user either:

  1. Asks a question and the Alexa skill gives a response.

    User: Alexa, ask Astrology Daily for the horoscope for Leo

    Astrology Daily: Today's outlook for Leo: An opportunity presents itself at work

  2. Tells the Alexa skill to do something, and the skill provides confirmation that action has been taken.

    User: Alexa, tell Score Keeper to give Tom five points.

    Score Keeper: Five points for Tom.

Whether the user "asks" or "tells" Alexa to interact with your skill, both approaches are quick exchanges where the user says something, Alexa promptly responds, and the interaction is over. Straightforward scenarios like these are both the most successful, and the most satisfying for users.

Below we outline three ways that users can access the capability you are creating, with tips on how to encourage your users to be successful with short interactions like the ones described above. Keep in mind that users will tend to say whatever is easiest for them, so it's important to guide them through the experience if your skill requires occasional longer interactions.

Note that the recommendations in this document apply to the custom interaction model you create for a custom skill. If you are using a pre-built model, you do not need to worry about building the interaction model yourself. For more about the different types of skills you can create, see [Understand the Different Skill Models][gs_skilltypes].

Supported Invocation Types

Users can start an interaction with your Alexa skill in three basic ways. The following invocation types are supported in the first release of the Alexa Skills Kit, with descriptions of each type in the sections below:

Full Intent

A "full intent" is a spoken request in which the user expresses everything required to complete their request (or intent) in a single utterance. Here is an example:

User: Alexa, ask Astrology Zone for the horoscope for Leo.

Astrology Zone: Today's outlook for Leo: An opportunity presents itself at work.

This type of interaction is the most common one, because users typically want their requests to be fulfilled in as few steps as possible, and they quickly learn that "full intent" expressions are the fastest path to doing so. When the user provides their complete request in their first utterance, your goal should be to successfully respond to their request in a succinct way (for examples, see What Alexa Says and end the interaction.

When you provide example interactions in your Skills Card (shown in the Alexa app when users browse for new Alexa abilities), you should only include "full intent" examples. That way, when users enable your skill, they will see the most efficient ways to successfully use it. We recommend providing examples that encompass the full range of functionality (think of these as the equivalent of the way you'd verbally describe how to use your skill to someone who'd never used it before). Here are some examples using an experience that keeps the score of a game:

  • User: Alexa, ask Score Keeper to start a new game

  • User: Alexa, ask Score Keeper to add John to the game

  • User: Alexa, ask Score Keeper to give 5 points to John.

  • User: Alexa, ask Score Keeper for the score

Partial Intent

Users are unpredictable, so you should also expect them to express just a subset of what is required for you to take action on their request. These are "partial intents." Here's an example:

User: Alexa, ask Astrology Daily for my horoscope.

Astrology Daily: Horoscope for what sign?

In this example, the user expressed an intent (for my horoscope), but did not give a required slot (a zodiac sign). If this occurs, you should recognize what is missing and follow up with the user to "fill in the blanks":

User: Alexa, ask Astrology Daily for my horoscope.

Do Don't
Astrology Daily: Horoscope for what sign?

User: Leo.

Astrology Daily: Today's outlook for Leo is …		 Astrology Daily: [plays error earcon; goes to sleep]

(If Astrology Daily failed to provide a response in this 'partial intent' use case, the interaction would time out. If the user wanted to interact with Astrology Daily, they would need to repeat their entire request, which is frustrating.)

No Intent

When users experience your capability for the first time, they may give only minimal information, for example, by simply asking Alexa to open your skill without providing any further detail. These are "no intent" use cases. When this happens, you need to tell them what options they have for interacting with your experience. Here's an example:

User: Alexa, open Car Fu.

Car Fu: Car Fu. You can ask to get a ride or request a fare estimate. Which will it be?

Guiding first-time users through the interaction is critical. To help them get started, we recommend presenting a short list of options to choose from. These menu-style prompts elicit a very limited set of responses, and generally should have no more than three options. When more than three options are offered, users will be overwhelmed by the number of choices and may have difficulty making a selection - they will become frustrated and will disengage.

Here is an example of this type of experience for a first-time user:

User: Alexa, open Car Fu.

Do Don't
Car Fu: Car Fu. You can ask to get a ride or request a fare estimate. Which will it be?

User: Get a ride.
Car Fu:
Sending your request. A mobile alert will let you know when your car arrives. Thanks for using Car Fu.		 Car Fu: Opening Car Fu.

User: (Here, it may not be obvious to users what they can do unless you give them some options)

Prompt Types

The Alexa Skills Kit supports two types of prompts (text that you specify and the user will hear in Alexa's voice). Each prompt type dictates whether the interaction will continue or end:

  1. Question: If your prompt ends with a question, you are inviting the user to continue the interaction:

    User: Alexa, open Astrology Daily and give me my horoscope.

    Astrology Daily: Horoscope for which sign?
    Interaction remains open, waiting for the user to respond.

  2. Statement: If your prompt ends with a statement, the interaction will end:

    User: Alexa, open Astrology Daily and give me the Pisces horoscope.

    Astrology Daily: Today's outlook for Pisces: You could be questioning your current path. Keep friends and family close since they will be your rock.
    Interaction ends.

Other Resources

If you're interested in learning more about designing voice interactions, see these additional resources:

Was this page helpful?

Last updated: Feb 27, 2023