Use Events in the Alexa Conversations Description Language

In the Alexa Conversations Description Language (ACDL), an event represents a trigger, such as something the user says. Events and actions, such as action invocations, make up the conversational experience of your skill. Alexa Conversations trains a model that predicts these actions given a variety of conditions, including the observation of the events.

When you declare an utterance event in ACDL, you specify an utterance set that contains language the user might say or type to trigger the event. You then use the event in a dialog sample, and in doing so you specify a request act that represents the goal of the user at that point in the conversation. In this way, you tie together user utterances with the goal of the user.

Declare an utterance event

You declare an utterance event from a set of utterances by using the utterances<T>() action from the Alexa Conversations Core Library (ACCL).

The utterances you provide in your utterance set 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 by using a set of utterances that use a custom type, CityAndDateType. You can also put utterance samples in separate lists (and files) as shown in Variations on how to define an utterance set.

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"
])

Use an utterance event

To use an event, you use the expect() action from the ACCL with a request act in a dialog sample. The request act indicates the goal of the user at that point in the conversation. The following is an example of using the expect() action for the event that the previous example defined.

dialog DialogName {
   sample {
      ...
      // An expression that represents an event with one of the getWeatherEvent utterances      
      weatherRequest = expect(Invoke, getWeatherEvent)
      ...
      // An expression that represents the invocation of an action      
      weatherResponse = getWeather(weatherRequest.cityName, weatherRequest.date)
   }
}

The available request acts are as follows:

  • Affirm – The user confirms a question that Alexa asked. ("Yes, I'd like the weather for Seattle.")
  • Deny – The user denies a question that Alexa asked. ("No, not that city.")
  • Inform – The user provides slots that are required to fulfill a goal or invoke an action. ("Tomorrow.")
  • Invoke – The user asks Alexa to perform an action or to achieve a goal. ("I'd like the weather for Seattle.").

The simulator uses this information to generate many more samples from which to train a model. At runtime, the model observes the stream of incoming events and predicts the actions that Alexa should take. For details, see How ACDL works with Alexa Conversations.

How the simulator matches events to actions

When generating the additional samples, the simulator only considers the sample utterances with arguments that are compatible with the arguments of the action. Properties that you specify in different orders, like {cityName, date} or {date, cityName}, are equivalent. The following examples show how the simulator only considers the sample utterances that match the action arguments of the corresponding request.

In the following example for getWeatherEvent, the simulator only considers samples that initialize both the cityName and date. Examples are "What's the weather {date} in {cityName}" and "How is the weather in {cityName} {date}".

dialog DialogName {
  sample {
    ...
    // An expression that represents an event with one of the getWeatherEvent samples
    // that specify both date and cityName
    weatherRequest = expect(Invoke, getWeatherEvent)

    // An expression representing the invocation of an action
    weatherResponse = getWeather(weatherRequest.cityName, weatherRequest.date)
    ...
  }
}

The properties in the weatherRequest are compatible with the arguments to the getWeather() action. Because the date and city are optional arguments to the getWeather() action, the action uses a default city and date if the user doesn't specify them. For examples of a getWeather() action declaration, see Use Actions in ACDL.

In the following example, there's an additional request for the cityName and date, so the simulator only considers the samples that aren't annotated using those properties. In this case, the samples are "how is the weather" and "what's the weather."

dialog DialogName {
  sample {
    ...
    // An expression that represents an event with one of the getWeatherEvent event samples
    // that specifies neither cityName nor date
    weatherRequest = expect(Invoke, getWeatherEvent)

    // Ensure that all of the required arguments for the getWeather action are requested
    ensure(
      {arguments = [getWeather.arguments.cityName], response = cityPrompt},
      {arguments = [getWeather.arguments.date], response = datePrompt}
    )

    // An expression that represents a request to the user for the city and the date
    response(response = request_city_date_prompt, act = Request {arguments = [getWeather.arguments.cityName]})

    // An expression representing information from the user with the city and the date
    informCityAndDate = expect(Inform, informCityAndDateEvent)
    city = informCityAndDate.cityName
    date = informCityAndDate.date

    // An expression that represents the invocation of an action
    weatherResponse = getWeather(city, date)
    ...
  }
}
Was this page helpful?

Last updated: Nov 27, 2023