ACDL Files for Alexa Conversations

Note: Sign in to the developer console to build or publish your skill.

Note: Alexa Conversations Description Language (ACDL) is offered as a beta and may change as we receive feedback and iterate on the feature.

Alexa Conversations Description Language (ACDL) files combine various Alexa Conversations assets to define sample conversations between the user and the skill. You express the sample conversations as annotated dialogs. The annotated dialogs link the events (such as user utterances) and actions (such as calling an API) that you expect to occur in your skill.

File location

ACDL files are in <skill-directory>/skill-package/conversations/.

File contents

Each ACDL file corresponds to a module. The module consists of a single namespace declaration, followed by zero or more import declarations, and one or more action declarations, type declarations, named expressions, or a dialog declaration.

module
   : namespaceDeclaration importDeclaration* (actionDeclaration | typeDeclaration | namedExpression | dialogDeclaration)+
;

A compilation request can have one or more modules that depend on each other. In this case, the compiler process all the modules together.

For the lexical structure of ACDL files, see Lexical Structure of ACDL.

ACDL file walkthrough

The following example takes you through the main concepts of ACDL as you create an ACDL file step by step. This example describes a simple interaction between a user and an Alexa skill that provides the weather forecast.

Create an empty ACDL file, which is just a text file with the extension *.acdl. For example, a weather skill might have the file WeatherDialog.acdl.
Declare a namespace in the file as follows.
```
namespace org.example.weather
```
Think of some utterances that users might say to ask for the weather. For example, a user might ask, "Get me the weather forecast in Seattle" or "I'd like to know the weather for Seattle."
Declare a type for the information you want to extract from the utterances. In this example, you want to extract the name of a city. You therefore declare a type that contains a property for the city in your ACDL file as follows.
```
type WeatherRequest {
  com.amazon.alexa.schema.String cityName
}
```
If you want to avoid specifying the entire namespace for String, you can import the namespace as follows.
```
import com.amazon.alexa.schema.String
type WeatherRequest {
  String cityName
}
```
Declare an event using your annotated utterances. In the following example, you declare WeatherEvent as the name for your set of annotated utterances. In your dialog sample, you use WeatherEvent to describe the user utterance event. Note the interpolated strings. The ACDL compiler makes sure that {cityName} matches one of the properties of the WeatherRequest type.
```
// Declare the list of utterances to represent the request for the weather
WeatherEvent = utterances<WeatherRequest>([
  "Get me the weather forecast in {cityName}",
  "I'd like to know the weather for {cityName}"
])
```
Describe the interaction using the business logic that is responsible for retrieving the weather forecast for a city. To do so, declare an action as follows.
```
action String getWeather(String cityName)
```
Use the elements you created in the previous steps to describe the following simple dialog flow:
1. The user says a request for the weather (expect())
2. The getWeather() action is invoked.
3. The result of the getWeather() action is used to generate a response to the user (response<T>()).
You represent this dialog as follows:
```
dialog Nothing WeatherDialog() {
   sample {
      req = expect(Invoke, WeatherEvent)
      weatherForecast = getWeather(req.cityName)
      response(forecastReport, Notify {actionName = getWeather, success = true}, payload = WeatherPayload {forecast = weatherForecast})
   }
}
```

Full ACDL file

The following example shows a complete ACDL file. For reference documentation, see the Alexa Conversations Core Library (ACCL) and ACDL reference documentation.

namespace org.example.weather

import prompts.forecastReport
import com.amazon.alexa.ask.conversations.*

// Declare the type for the APLA document's payload
type WeatherPayload {
  String forecast
}

// Declare a type to represent the information that 
// will be extracted from the utterance event
type WeatherRequest {
  String cityName
}

// Declare the list of utterances to represent the request for the weather
WeatherEvent = utterances<WeatherRequest>([
  "Get me the weather forecast in {cityName}",
  "I'd like to know the weather for {cityName}"
])

// Declare the signature of an action to represent the skill logic
// that retrieves the forecast given the name of a city.
action String getWeather(String cityName)

// Describe the dialog flow
dialog Nothing GetWeatherDialog() {
  sample {
    // Declare the expectation that the user will ask for the weather
    req = expect(Invoke, WeatherEvent)

    // Describe the action that represents the skill's logic to retrieve
    // the result following the above event
    weatherForecast = getWeather(req.cityName)

    // Describe the action that represents the response to the user.
    // The "forecastReport" is the name of the APLA document which is
    // declared as a separate JSON-based document outside of ACDL.
    // The ACDL compiler creates the name automatically in the "prompts" namespace.
    response(forecastReport, Notify {actionName = getWeather, success = true}, payload = WeatherPayload {forecast = weatherForecast})
  }
}

Was this page helpful?

Provide feedback

Last updated: Nov 27, 2023