Utterance Sets in the Alexa Conversations Core Library

Utterance sets contain sample variations in how a user might say a response or request.

For example, in a Weather Bot skill, the user might ask for the weather by saying "What's the weather?" "How's the weather in Seattle?" "What's the weather in Seattle tomorrow?" and so on. Those utterances all represent the same request, so you provide them as sample utterances to the same utterance set.

In the Alexa Conversations Description Language (ACDL), you define an utterance set as a list of strings. You then declare events that associate the utterance set with the purpose of the user by specifying a request act.

Declare an event using an utterance set

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

If you want to use a custom type in an utterance set, you must declare the type in the interaction model file of the skill. For details, see Type Declarations in ACDL and Interaction Model Files for Alexa Conversations. You don't need to declare built-in types, such as AMAZON.US_CITY and AMAZON.DATE, in the interaction model file.

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

type CityAndDateType {
  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 optionally reference slots by using curly brace notation.

Variations on how to define an utterance set

The following are variations on how you can define an utterance set.

Omit the utterance event type

The utterance event doesn't need to have a type argument if the samples don't use any types. This is a common case for Affirm events, which usually appear after a request from Alexa for confirmation and therefore don't need to provide information. The following example shows an Affirm event.

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

Put the utterance samples in standalone lists

You can declare sample utterances 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)

Put the utterance samples in a separate ACDL file

Because you can declare sample utterances in separate lists, you can put utterance sample lists in a separate file. Utterance sample lists are in namespaces, so you can declare the utterance sample lists in one ACDL file and then use or reuse them in other ACDL files. You can import the utterance samples into any ACDL file. The following example 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 those utterances in the dialog by importing them into another ACDL file, as shown 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 {
  US_CITY cityName
  NUMBER temperature
}

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

action WeatherResult getWeather(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})
  }
}