Utterance Sets in the Alexa Conversations Core Library

Utterance sets are sample variations in the words a user might choose to ask Alexa a question or offer a response. In a Weather Bot skill, for example, the user might ask for the weather with one of the following utterances or some similar variation.

"What's the weather?"
"How's the weather in Seattle?"
"What's the weather in Seattle tomorrow?"

These sample utterances all represent the same request, so they belong to the same utterance set.

Use an utterance set to declare an event

In the Alexa Conversations Description Language (ACDL), an utterance set is defined as a list of strings. Then events are declared that associate the utterance set with the user's intention by specifying a request act.

The utterances<T>() action from the Alexa Conversations Core Library (ACCL) declares an event from a set of utterances. These utterances are variations of the user utterances that might trigger the declared event.

To use a custom type in an utterance set, you must declare the type in the interaction model file for the skill. For details, see Type Declarations in ACDL and Interaction Model Files for Alexa Conversations.

The following example shows how to declare an event using a set of utterances that have a custom type, CityAndDateType.

type CityAndDateType {
  AMAZON.US_CITY cityName
  DATE date
}

getWeatherEvent = utterances<CityAndDateType>([
  "What's the weather {date} in {cityName}",
  "What is the weather {date}",
  "How is the weather {date}",
  "How is the weather in {cityName} {date}",
  "How is the weather",
  "Can you please give me the weather report for {date}",
  "What's the weather"
])

As shown in the previous example, utterances can reference slots by using curly brace notation.

Define utterance sets

You can define an utterance set in various ways.

Omit the utterance event type

If your utterance samples don't use types, the utterance event doesn't need a type argument. This is common in Affirm events, which usually appear after Alexa requests user confirmation. Affirm events like the one in the following example, then, don't need to provide information.

affirmEvent = utterances([
  "Yes",
  "That's correct",
  "Yeah"
])

Put utterance samples in a standalone list

You can declare a sample utterance set separately, as a list of strings.

utteranceSamples = [
  "What's the weather {date} in {cityName}",
  "What is the weather {date}",
  "How is the weather {date}"
]

getWeatherEvent = utterances<CityAndDateType>(utteranceSamples)

Store utterance samples in a separate ACDL file

Because you can declare sample utterances in separate lists, you can house such lists in separate files. Utterance sample lists are in namespaces, so you can declare an utterance sample list in one ACDL file and then use or reuse it in other ACDL files. You can import the utterance samples into any ACDL file. For instance, the following utterance set might be in one ACDL file.

namespace com.weatherbot.utterances

getWeatherUtterances = [
  "What's the weather {date} in {cityName}",
  "What is the weather {date}",
  "How is the weather {date}",
  "What's the weather"
]

informUtterances = [
  "For {cityName} {date}"
]

You then use these utterances in a dialog by importing them into another ACDL file, as in the following examples.

namespace com.weatherbot.dialogs

import com.weatherbot.utterances.getWeatherUtterances // Import the utterances from the other namespace
import com.weatherbot.utterances.informUtterances
import prompts.request_city_date_prompt
import prompts.weather_prompt
import prompts.cityPrompt
import prompts.datePrompt

type WeatherResult {
  AMAZON.US_CITY cityName
  NUMBER temperature
}

type CityAndDateType { // Declare the type that the utterance event uses
  AMAZON.US_CITY cityName
  DATE date
}

action WeatherResult getWeather(AMAZON.US_CITY cityName, DATE date)

// Declare the utterance events with the list of utterance samples as the argument to the utterances<T>() action
getWeatherEvent = utterances<CityAndDateType>(getWeatherUtterances)
informCityDateEvent = utterances<CityAndDateType>(informUtterances)

dialog Weather {
  sample {
    weatherRequest = expect(Invoke, getWeatherEvent)
    ensure(
            {arguments = [getWeather.arguments.cityName], response = cityPrompt},
            {arguments = [getWeather.arguments.date], response = datePrompt}
    )
    response(request_city_date_prompt, Request {arguments = [getWeather.arguments.cityName, getWeather.arguments.date]})
    cityNameDate = expect(Inform, informCityDateEvent)
    weatherResult = getWeather(cityNameDate.cityName, date = cityNameDate.date)
    response(weather_prompt, Notify {actionName = getWeather, success = true}, payload = {weatherResult = weatherResult})
   }

  sample {
    weatherRequest = expect(Invoke, getWeatherEvent)
    ensure(
      {arguments = [getWeather.arguments.cityName], response = cityPrompt},
      {arguments = [getWeather.arguments.date], response = datePrompt}
    )
    response(request_city_date_prompt, Request {arguments = [getWeather.arguments.cityName, getWeather.arguments.date]})
    cityNameDate = expect(Inform, informCityDateEvent)
    weatherResult = getWeather(cityNameDate.cityName, cityNameDate.date)
    response(weather_prompt, Notify {actionName = getWeather, success = true}, payload = {weatherResult = weatherResult})
  }
}
Was this page helpful?

Last updated: Nov 27, 2023