Actions in the Alexa Conversations Core Library

The Alexa Conversations Core Library (ACCL) provides a list of built-in actions and types that you use in Alexa Conversations Description Language (ACDL) files.

The ACCL is in the com.amazon.alexa.ask.conversations namespace, which the ACDL compiler automatically imports into each ACDL file. You therefore don't need to manually import the library or declare these actions when you use them in dialog samples.

Overview

The following table shows actions ACCL provides.

For details, see Use Actions in ACDL.

and()

Represents a Boolean "and" operation. Returns true if both operands are true. Otherwise, returns false.

Signature

action Boolean and(Boolean left, Boolean right)

apl<T>()

Identifies a path to an APL document, which specifies a visual response.

Signature

action APL<T> apl<T>(Path path)

Example

The following example shows how to use the apl() action.

request_city_date_apl = apl<CityAndDate>("/lib/displays/en/request_city_date")

// You can annotate the name declaration with the locale.
@locale(Locale.en_US, Locale.en_GB, Locale.en_CA)
request_city_date_apl = apl<CityAndDate>("/lib/displays/en/request_city_date")

apla<T>()

Identifies a path to an APLA document, which specifies an audio response.

Signature

action APLA<T> apla<T>(Path path)

Example

The following example shows how to use the apla() action.

request_city_date_apla = apla<CityAndDate>("/lib/prompts/en/request_city_date")

// You can annotate the name declaration with the apla() action with the locale.
@locale(Locale.en_US, Locale.en_GB, Locale.en_CA)
request_city_date_apla = apla<CityAndDate>("/lib/prompts/en/request_city_date")

confirmAction<T>()

Confirms that an action should be invoked. Returns void. You can use confirmAction<T>() before an action to indicate that the skill should check with the user before proceeding. This action is the equivalent of using the response<T>() action with the ConfirmAction response act.

Signature

action void confirmAction<T>(
  Response<T> response,
  Action actionName,
  optional T payload
)

Example

In the following example, the skill asks the user to confirm that they want to proceed with the invocation of the bookFlight() action.

sample {
  ...
  confirmAction(
    confirmFlightBooking,
    bookFlight,
    FlightResultPayload {searchResult = searchFlightResult}
  )
  ...
}

The previous example is a less verbose version of the following example.

sample {
  ...
  response(
    confirmFlightBooking,
    ConfirmAction {actionName = bookFlight},
    payload = FlightResultPayload {searchResult = searchFlightResult}
  )
  ...
}

confirmArgs<T>()

Confirms the arguments the user provided. Returns void. You can use the confirmArgs<T>() action before invoking an action to indicate that the skill should check the values of the action argument(s) with the user before proceeding.

The confirmArgs<T>() action is the equivalent of a response<T>() action with a ConfirmArgs response act paired with an expect() action that uses the Affirm request act.

You can't follow the confirmArgs<T>() action with an expect() action that uses the Affirm or Deny request act. To use the Affirm request act next, you must use the response<T>() action with the Confirm response act.

Signature

action void confirmArgs<T>(
  List<ConfirmArguments<T>> confirmArgs
)

Example

In the following example, the skill requests the user to confirm the fromCity argument before invoking the bookFlight() action.

sample {
  bookFlightRequest = expect(Invoke, bookFlightEvent)
  ...
  // Make sure that the user has provided the specified argument.
  ensure(
    RequestArguments {arguments = [searchFlights.arguments.fromCity], response = cityPrompt},
  )

  // Ask the user to confirm that the provided answer is indeed what they want to use
  confirmArgs([
    ConfirmArguments { arguments = [searchFlights.arguments.fromCity], response = confirmFromCityPrompt}
  ])

  ...

  searchFlightResult = searchFlights(bookFlightRequest.fromCity, bookFlightRequest.toCity, bookFlightRequest.startDate)
}

The previous example is a less verbose version of the following example.

sample {
  bookFlightRequest = expect(Invoke, bookFlightEvent)
  ...
  // Make sure that user has provided the identified argument.
  ensure(
    RequestArguments {arguments = [searchFlights.arguments.fromCity], response = cityPrompt},
  )

  // Ask the user to confirm that the answer provided.
  response(
    confirmFromCityPrompt,
    ConfirmArgs {arguments = [searchFlights.arguments.fromCity]},
    payload = FlightResultPayload { fromCity = bookFlightRequest.fromCity }
  )

  ...

  searchFlightResult = searchFlights(bookFlightRequest.fromCity, bookFlightRequest.toCity, bookFlightRequest.startDate)
}

ensure<T>()

Represents the requirement that the referenced action argument must be given a value. Returns void. If the user hasn't already provided a value for the argument, the skill requests the value from the user. You can extract the required value for the argument from an event by using the expect() action or by a call to an action.

The ensure<T>() action is the equivalent of a response<T>() action with a Request response act paired with an expect() action.

You can't follow an ensure<T>() action with a response<T>() action that uses the Inform request act. If you want to use the Inform request act next, use the response<T>() action with the Request response act.

Signature

action void ensure<T>(Args<RequestArguments<T>> requestArgs)

Example 1

In the following example, the expected event might not produce a value for the optional arguments. The ensure<T>() action indicates to Alexa Conversations to simulate interactions that ask the user to provide those values. The ensure<T>() action in the example provides a response expression for each of the arguments.

In this example, the ensure<T>() action replaces the three pairs of response<T>() and expect() actions shown in the example in Request.

  sample {
    // "Book a flight."
    // "Book a flight from Seattle."
    // "Book a flight from Seattle to New York City."
    // "Book a flight from Seattle to New York City for Jan 10th."
    bookFlightRequest = expect(Invoke, bookFlightEvent)

    ensure(
      RequestArguments { arguments = [searchFlights.arguments.fromCity], response = fromCityPrompt},
      RequestArguments { arguments = [searchFlights.arguments.toCity], response = toCityPrompt},
      RequestArguments { arguments = [searchFlights.arguments.startDate], response = startDatePrompt}
    )
    
    searchFlightResult = searchFlights(bookFlightRequest.fromCity, bookFlightRequest.toCity, bookFlightRequest.startDate)
    ...
  }

The single ensure<T>() action in the previous example might result in three different prompts, depending on which arguments have no values. It's also possible to request multiple arguments with a single prompt. The following example assumes that the expect() action either extracts values for both fromCity and toCity or provides values for neither. This can happen if both event type properties are optional.

  type FlightSearchRequest {
    optional String fromCity
    optional String toCity
  }

  bookFlightEvent = utterances([
      "Book a flight",
      "Book a flight from {fromCity} to {toCity}"
  ])

  sample {
    bookFlightRequest = expect(Invoke, bookFlightEvent)

    ensure(
      RequestArguments { arguments = [searchFlights.arguments.fromCity, searchFlights.arguments.toCity], response = fromAndToCityPrompt},
    )
    
    searchFlightResult = searchFlights(bookFlightRequest.fromCity, bookFlightRequest.toCity)
    
    ...
  }

Example 2

If a sample doesn't have a response<T>() action for each referenced action argument that is required, you can use an ensure<T>() to cover the remaining referenced action arguments, as shown in the following example.

sample {
  // "Book a flight on July 31st."
  bookFlightRequest = expect(Invoke, bookFlightEvent)

  // "To which city?"
  response(response = toCityPrompt, act = Request {arguments = [searchFlights.arguments.toCity]})

  // "To Portland."
  toCityResponse = expect(Inform, informCityEvent)

  // "From which city?"
  response(response = fromCityPrompt, act = Request {arguments = [searchFlights.arguments.fromCity]})

  // "From Seattle."
  fromCityResponse = expect(Inform, informCityEvent)

  // There is no "response<T>()" action for the "startDate" argument, so the "ensure<T>()" action will simulate interactions in which the user is asked to provide that argument value.
  ensure(
    {arguments = [searchFlights.arguments.startDate], response = datePrompt}
  )

  searchFlightResult = searchFlights(fromCityResponse.fromCity, toCityResponse.toCity, bookFlightRequest.startDate)
  ...
}

equal<T>()

Represents an equality comparison. Returns true if the two operands are equal. Otherwise, returns false.

Signature

action Boolean equal<T>(T left, T right)

exists(Thing target)

Returns true if the target exists.

Signature

action Boolean exists(Thing target)

expect()

Represents the expectation of an event. Returns an expression, of type T, that represents the properties of an event.

Alexa Conversations interprets the expect() action as the representation of an incoming event. The Alexa Conversations simulator generates the representative events that the skill might receive. The simulator uses the information provided to the expect() action to create variations of the events. The most common type of event to pass to the expect() action is an UtteranceEvent.

For details, see How ACDL works with Alexa Conversations.

Signature

action T expect<T>(Type<RequestAct> act, Event<T> event)

Example

In the following example, the WeatherRequest type represents the properties of an UtteranceEvent. The utterances<T>() action declares the UtteranceEvent by using the WeatherEvent expression, which represents variations of how a user might request the weather forecast.

Finally, the expect() action represents the user's request for the weather forecast. Invoke is a RequestAct that indicates to Alexa Conversations that these utterances might be used to initiate a dialog about the forecast.

namespace org.example.weather

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

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

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

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

    ...
  }
}

ge()

Represents a "greater than or equal to" comparison. Returns true if the left number is greater than or equal to the right number. Otherwise, returns false.

Signature

action Boolean ge(Number left, Number right)

gt()

Represents a "greater than" comparison. Returns true if the left number is greater than the right number. Otherwise, returns false.

Signature

action Boolean gt(Number left, Number right)

in(T entity, List entities)

Returns true if the entity is one of the specified entities.

Signature

action Boolean in<T>(T entity, List<T> entities)

isInCatalog(T entity)

Returns true if the entity has a valid catalog value. The entity's catalog value results from a call to expect() or external action.

Signature

action Boolean isInCatalog<T>(T entity)

le()

Represents a "less than or equal to" comparison. Returns true if the left number is less than or equal to the right number. Otherwise, returns false.

Signature

action Boolean le(Number left, Number right)

length()

Represents the length of a string.

Signature

action Number length(String string)

lt()

Represents a "less than" comparison. Returns true if the left number is less than the right number. Otherwise, returns false.

Signature

action Boolean lt(Number left, Number right)

not()

Represents a negation operation. Returns true if the expression is false. Otherwise, returns false.

Signature

action Boolean not(Boolean expression)

notEqual<T>()

Represents a non-equality comparison. Returns true if the two operands aren't equal. Otherwise, returns false.

Signature

action Boolean notEqual<T>(T left, T right)

or()

Represents a Boolean "or" operation. Returns true if either or both operands are true. Otherwise, returns false.

Signature

action Boolean or(Boolean left, Boolean right)

response<T>()

Represents a skill response to the user. Returns void.

Alexa Conversations interprets the response<T>() action as the representation of a response from the skill to the user. The Alexa Conversations simulator generates variations of the response from the provided APL/APLA templates and the payload. The simulator also considers the provided response act(s) in determining the semantics of the response (for example, the response is a question, a report of successful completion of the action, and so on).

The payload expression passes the data to be rendered to the APL and APLA documents. For examples of APLA documents, see Response Prompt Files for Alexa Conversations.

For details about using the response<T>() action, see Use Responses in ACDL. For a discussion about the role of events and actions in describing the conversational flow in a dialog sample, see How ACDL works with Alexa Conversations.

Signature

action void response<T>(
  Response<T> response,
  ResponseAct act,
  optional ResponseAct nextAct,
  optional T payload
)

Example

In the following example, you describe the response to return the user after the skill retrieves the weather forecast. The response uses the forecastReport template to format the output (for example, an APL document, an APLA document, or both). The forecastReport is a reference to the APL or APLA document. Alexa Conversations automatically creates the reference.

The Notify expression in the response<T>() action indicates to the Alexa Conversations simulator that this response is a notification to the user. Notify, which is one of the available response acts, indicates that getWeather() was invoked successfully. Finally, the WeatherPayload expression represents the information that is passed to the given APL or APLA document.

  namespace org.example.weather

  import prompts.forecastReport

  ...

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

  ...

  // Describe the dialog flow
  dialog Weather() {
    sample {
      ...

      // Representation of the call to get the weather forecast
      weatherForecast = getWeather(req.cityName)

      // Representation of the response to the user
      response(forecastReport, Notify {actionName = getWeather, success = true}, payload = WeatherPayload {forecast = weatherForecast})
    }
  }

size()

Represents the size of a list.

Signature

action Number size<T>(List<T> list)

skill()

Specifies a set of skill-wide assets for one or more locales that the skill supports.

Signature

action Skill skill( 
  List<Locale> locales,
  SkillLevelResponses skillLevelResponses
)

Example

The following example uses the skill action to bring together the skill-level responses for a Weather Bot skill that supports the en-US and de-DE locales.

@locale(Locale.en_US)
welcome_en = apla("/lib/prompts/en/welcome")
@locale(Locale.de_DE)
welcome_de = apla("/lib/prompts/de/welcome")
welcome = variations(welcome_en, welcome_de)

@locale(Locale.en_US)
out_of_domain_en = apla("/lib/prompts/en/out_of_domain")
@locale(Locale.de_DE)
out_of_domain_de = apla("/lib/prompts/de/out_of_domain")
out_of_domain = variations(out_of_domain_en, out_of_domain_de)
 
@locale(Locale.en_US)
bye_en = apla("/lib/prompts/en/bye")
@locale(Locale.de_DE)
bye_de = apla("/lib/prompts/de/bye")
bye = variations(bye_en, bye_de)

@locale(Locale.en_US)
reqmore_en = apla("/lib/prompts/en/reqmore")
@locale(Locale.de_DE)
reqmore_de = apla("/lib/prompts/de/reqmore")
reqmore = variations(reqmore_en, reqmore_de)

@locale(Locale.en_US)
provide_help_en = apla("/lib/prompts/en/provide_help")
@locale(Locale.de_DE)
provide_help_de = apla("/lib/prompts/de/provide_help")
provide_help = variations(provide_help_en, provide_help_de)

mySkill = skill(
   locales = [Locale.en_US, Locale.en_GB],
   skillLevelResponses = SkillLevelResponses
     {
        welcome = welcome,
        out_of_domain = out_of_domain,
        bye = bye,
        reqmore = reqmore,
        provide_help = provide_help
     }
)

dialog Weather {

}

utterances<T>()

Represents an utterance event. The given utterances represent variations of the utterances that trigger the event. Returns an UtteranceEvent. The utterances() action supports the @locale annotation.

Alexa Conversations interprets the utterances<T>() action as the representation of an UtteranceEvent. You use the utterances<T>() action to describe to Alexa Conversations the UtteranceEvent in terms of a set of utterance samples. When you use an expect() action in a dialog sample, the Alexa Conversations simulator uses the set of utterance samples to generate variations of this event (that is, input from the user).

Each string in the list of samples to the utterances<T>() action may contain references to the properties of the given T type. You annotate the references by using the { <property-name> } syntax<StringInterpolation> inside the string. Alexa Conversations treats the references as placeholders for what the user might say. Alexa Conversations also considers the type of the property when creating variations of the event.

Signature

action UtteranceEvent<T> utterances<T>(List<Utterance<T>> samples)

Examples

The following example shows how to use the utterances<T>() action with the @locale annotation.

@locale(Locale.en_US, Locale.en_GB, Locale.en_CA)
getWeatherEvent = utterances<CityAndDate>(
    [
        "What's the weather {date} in {cityName}",
        "what is the weather {date}",
        "How is the weather in {cityName}",
        "How is weather in {cityName} {date}",
        "how is weather",
        "can you please give me weather report for {date}"
    ]
)

The following example shows how to aggregate utterances by using the variations() action.

@locale(Locale.en_US, Locale.en_GB, Locale.en_CA)
getWeatherEventEn = utterances<CityAndDate>(
    [
        ...
    ]
)

@locale(Locale.de_DE)
getWeatherEventDe = utterances<CityAndDate>(
    [
        ...
    ]
)

getWeatherEvent = variations(getWeatherEventEn, getWeatherEventDe)

dialog Weather {
   sample {
        request = expect(Invoke, getWeatherEvent)
        ...
   }
}

variations()

Aggregates expressions of the same type. You can only use variations() at the namespace level.

Signature

action T variations<T>(Args<T> variations)

Examples

The following example uses the variations<T>() action to aggregate APLA documents for different locales.

@locale(Locale.en_US, Locale.en_GB)
requestCrustAplaEn = apla<CrustType>("/lib/prompts/en/request_crust_apla")

@locale(Locale.de_DE)
requestCrustAplaDe = apla<CrustType>("/lib/prompts/de/request_crust_apla")

requestCrustApla = variations(requestCrustAplaEn, requestCrustAplaDe) // This is of type APLA<CrustType>.

The following example returns a compilation error because it doesn't use variations() at the namespace level.

// INVALID. RETURNS AN ERROR.
dialog Weather { 
    sample {
        request = expect(Invoke, variations(getWeatherEventEn, getWeatherEventDe))
        ....
    }
}

Related topics

• Types in the ACCL
• Annotations in the ACCL
• Use Actions in ACDL
• About Alexa Conversations Description Language

Last updated: Nov 27, 2023