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.

Action Description
and() Represents a Boolean "and" operation.
apl<T> Identifies a path to an Alexa Presentation Language (APL) document, which specifies a visual response.
apla<T> Specifies a path to an APL for Audio (APLA) document, which specifies an audio response.
confirmAction<T>() Confirms that an action should be invoked.
confirmArgs<T>() Confirms the arguments the user provided.
ensure<T>() Represents the requirement that the referenced action argument must be given a value.
equal<T>() Represents an equality comparison.
expect() Represents the expectation of an event.
ge() Represents a "greater than or equal to" comparison.
gt() Represents a "greater than" comparison.
le() Represents a "less than or equal to" comparison.
length() Represents the length of a string.
lt() Represents a "less than" comparison.
not() Represents a negation operation.
notEqual<T>() Represents a non-equality comparison.
or() Represents a Boolean "or" operation.
response<T>() Represents a skill's response to the user.
size() Represents the size of a list.
skill() Specifies a set of skill-wide assets for one or more locales that the skill supports.
utterances<T>() Represents an utterance event.
variations() Aggregates expressions of the same type.

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)
Parameter Description Type Required
left The left operand. Boolean Yes
right The right operand. Boolean Yes

apl<T>()

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

Signature

action APL<T> apl<T>(Path path)
Parameter Description Type Required
path A path to an APL document in the local file system. The ACDL compiler will automatically copy the document to skill-package/response/display. Path Yes

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)
Parameter Description Type Required
path A path to an APLA document in the local file system. The ACDL compiler will automatically copy the document to skill-package/response/prompts. Path Yes

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
)
Parameter Description Type Required
response The response that asks the user to confirm the action. Response<T> Yes
actionName The action to confirm. Action Yes
payload The payload, if any, to pass to the APLA and APL documents of the response. The response prompt uses the payload to access arguments that the dialog samples provide. For example, to access arguments called fromCity and toCity, an APLA document might use the following line: "content": "Just to confirm, you want to book a flight from ${payload.fromCity} to ${payload.toCity}?" T No

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
)
Parameter Description Type Required
confirmArgs The list of arguments to confirm. List<ConfirmArguments<T>> Yes

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)
Parameter Description Type Required
requestArgs A variable list of required action arguments that don't have request expressions explicitly defined in the dialog sample. Args <RequestArguments<T>> Yes

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)
Parameter Description Type Required
T The type of operands in the comparison. Type Yes
left The left operand in the comparison. Boolean Yes
right The right operand in the comparison. Boolean Yes

exists(Thing target)

Returns true if the target exists.

Signature

action Boolean exists(Thing target)
Parameter Description Type Required

target

Target whose existence is to be checked.

Thing

Yes

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)
Parameter Description Type Required
T The type that is used to represent the properties of the event. Type Yes
act A request act that indicates the purpose of the user. Type<RequestAct> Yes
event The event to which to associate the specified request act. Event<T> Yes

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)
Parameter Description Type Required
left The left number in the comparison. Number Yes
right The right number in the comparison. Number Yes

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)
Parameter Description Type Required
left The left number in the comparison. Number Yes
right The right number in the comparison. Number Yes

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)
Parameter Description Type Required

T

Type of entity.

Type

Yes

entity

Entity to check.

T

Yes

entities

List of values that the entity belongs to.

List

Yes

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)
Parameter Description Type Required

T

Type of entity.

Type

Yes

entity

Entity to check for a valid catalog value.

T

Yes

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)
Parameter Description Type Required
left The left number in the comparison. Number Yes
right The right number in the comparison. Number Yes

length()

Represents the length of a string.

Signature

action Number length(String string)
Parameter Description Type Required
string The string for which to get the length. String Yes

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)
Parameter Description Type Required
left The left number in the comparison. Number Yes
right The right number in the comparison. Number Yes

not()

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

Signature

action Boolean not(Boolean expression)
Parameter Description Type Required
expression The Boolean expression to negate. Boolean Yes

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)
Parameter Description Type Required
T The type of operands in the comparison. Type Yes
left The left operand in the comparison. Boolean Yes
right The right operand in the comparison. Boolean Yes

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)
Parameter Description Type Required
left The left operand. Boolean Yes
right The right operand. Boolean Yes

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
)
Parameter Description Type Required
response The reference to the APL or APLA document to use. Response<T> Yes
act The response act associated with the response. ResponseAct Yes
nextAct An optional follow-up response act that indicates the purpose of the next response, if you're chaining response acts. ResponseAct No
payload An optional payload to pass to the APLA and APL documents of the response. The response prompt uses the payload to access arguments that the dialog samples provide. For example, to access arguments called fromCity and toCity, an APLA document might use the following line: "content": "Just to confirm, you want to book a flight from ${payload.fromCity} to ${payload.toCity}?" T No

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)
Parameter Description Type Required
list The list for which to get the size. List<T> Yes

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
)
Parameter Description Type Required
locales A list of locales that the skill supports. You must provide at least one locale. List<Locale> Yes
skillLevelResponses Paths to the APL or APLA documents to use for the skill-level response in the specified locales. SkillLevelResponses Yes

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)
Parameter Description Type Required
T The type that is used to represent the properties of the event. Type Yes
samples A list of user utterances that trigger the event. For details, see Utterance Sets in the ACCL. List<Utterance<T>> Yes

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)
Parameter Description Type Required
variations One or more variations that share the same type. Args<T> Yes

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))
        ....
    }
}

Was this page helpful?

Last updated: Nov 27, 2023