Best Practices for Sample Utterances and Custom Slot Type Values

The usability of the skill directly depends on how well the sample utterances and custom slot values represent real-world language use.

Building a representative set of custom values and sample utterances is an important process and one that requires iteration. During development and testing, try using many different phrases to invoke each intent. If you can observe other users during testing, note the phrases that they speak to invoke each intent. Continually update the custom values and sample utterances file to ensure that it includes instances of your users’ most common phrasings.

The following sections provide recommendations for developing your set of sample utterances.

Sample Utterance Phrasing

Given the flexibility and variation of spoken language in the real world, there will often be many different ways to express the same request. For example, to ask for a horoscope a user might say:

  • what is the horoscope
  • get me my horoscope
  • tell me the horoscope
  • how’s my horoscope today

Or any other variations on the above forms:

  • “what’s” and “what is”
  • “get”, “tell”, and “give”
  • “my” and “the”

If you have requests that are full sentences, think about shortened ways that users might say them, especially when combined with the Ask/Tell starting phrases, with patterns like Ask…to… and Ask…about…. For instance, if you have “what’s the weather,” consider also just “weather”. This works well with patterns such as “Ask <invocation name> for weather.” or “Ask <invocation name> about weather”.

Providing these different phrases in your sample utterances will help improve voice recognition for the abilities you add to Alexa. It is important to include as wide a range of representative samples as you can -– all the phrases that you can think of that are possible in use (though do not include samples that users will never speak). Alexa also attempts to generalize based on the samples you provide to interpret spoken phrases that differ in minor ways from the samples specified.

Sample Utterances for Starting a Conversation

The preferred phrases for beginning an interaction with an Alexa ability are ask and tell. These can be used to ask questions or state commands in a very natural way. Your sample utterances should flow naturally when combined with these phrases.

For example, users might say one of the following to request a horoscope:

  • “Alexa, ask Daily Horoscopes for the horoscope for Gemini
  • “Alexa, ask Daily Horoscopes about Gemini
  • “Alexa, ask Daily Horoscopes what is the horoscope for Gemini
  • “Alexa, ask Daily Horoscopes what’s the horoscope for Gemini
  • “Alexa, ask Daily Horoscopes to give me the horoscope for Gemini
  • “Alexa, ask Daily Horoscopes to tell me the horoscope for Gemini

Note the different forms of the sample utterances that work effectively with different variations of “ask”:

  • Noun utterances:
    • “the horoscope for…”
    • “Gemini”
  • Question utterances:
    • “what is the horoscope for…”
    • “what’s the horoscope for…”
  • Verb utterances:
    • “give me the horoscope for”
    • “tell me the horoscope for…”

In the syntax of the sample utterances, these would be specified as follows:

the horoscope for {Sign} 
what's the horoscope for {Sign}
what is the horoscope for {Sign}
give me the horoscope for {Sign}
tell me the horoscope for {Sign}

Utterances that begin with specific question words (“what”, “how”, “where”, and so on) are especially important, as these work with the “ask <invocation name> question” variation. The following words are considered question words that work with ask:

  • who, what, why, when, where, which, how
  • do, did, does
  • can, could, should, would, may, must, shall
  • is, was, will, am, are, were
  • have, has, had
  • Some variants of the above, such as: what’s, whose, didn’t, ain’t

When writing utterances as questions, also consider multiple forms of the question. For example:

  • “what is my horoscope”. (“Alexa, ask Daily Horoscopes what is my horoscope”)
  • “what my horoscope is” (“Alexa, ask Daily Horoscopes what my horoscope is”)

Not all of these question words may work well for all Alexa capabilities, but you should include utterances for these words when they represent real-world language use. For the full list of phrases users can say to begin interacting with your Alexa skill, see Understanding How Users Invoke Custom Skills. Include utterances that work naturally with as many of these phrases as possible.

Number of Sample Utterances

For each intent, include as many variations of the phrases as you expect users to speak. For example, for the utterance “what is my horoscope”, include variations such as:

  • “what is…”
  • “what’s…”
  • “tell me…”
  • “give…”
  • “give me…”
  • “get…”
  • “get me…”
  • “find…”
  • “find me…”

It is better to provide too many samples than to provide too few, so test different phrases and add additional phrases as needed.

Recommendations for Custom Slot Type Values

When using custom slot types, make sure the list of values provided for the slot comprehensively covers the expected input from your users. While this is relatively straightforward in the horoscopes example –- in this case the set of twelve signs is small, finite and has few or no variations in terms of how people are likely to speak each sign –- it can be more difficult as the complexity of input to a given slot increases. Tips to build representative coverage for more complex slot types include:

  • Start with data sources that reflect real usage. For instance, if you have a web version of your application that can use items you’ve logged from users via forms or search queries, use those. Otherwise look for other data sources representing likelihood of input.

    If you’re building a list of ingredients for a recipe skill for instance, generate a list of all ingredients used in all recipes, and validate that against other lists you may be able to find online of common ingredients.

  • Your skill can have a total of 50,000 custom slot values. This is totaled across all custom slots used in the interaction model. If you need to scale back the number of values to fit within this limit, be sure to keep the values most likely to be used.
  • If your list of custom values does not contain all the values your skill expects, provide a representative set of custom values with representative word counts. For instance, if values of one to four words are possible, use values of one to four words in your value list. But also be sure to distribute them proportionally. If a four-word value occurs in an estimated 10% of inputs, then include four-word values only in 10% of the values in your list.

Slot values are sent to your skill in written format. For example, both “fire h.d. 7” and “fire h.d. seven” would be sent to your skill as “Fire HD7”. For better recognition, acronyms and other phrases involving spoken letters should either be all caps (“HD”) or separated by periods and spaces (“h. d. “). Using lowercase for initialisms may lead to unreliable recognition since the spoken form may not correctly be detected. See examples.