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.
confirmAction() Confirms that an action should be invoked.
confirmArgs() Confirms the arguments the user provided.
ensure() 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() Represents a skill response to the user.
size() Represents the size of a list.
utterances<T>() Represents an utterance event.

For details about how to use actions, 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

confirmAction()

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

Signature

action Nothing confirmAction(Response response, Action actionName, Thing payload = nothing)
Parameter Description Type Required
response The response that asks the user to confirm the action. Response 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}?" Thing No

Example

In the following example, the skill requests 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()

Confirms the arguments the user provided. You can use the confirmArgs() 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() action is the equivalent of a response() action with a ConfirmArgs response act paired with an expect() action that uses the Affirm request act.

You can't follow the confirmArgs() 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() action with the Confirm response act.

Signature

action Nothing confirmArgs(List<ConfirmArguments> confirmArgs)
Parameter Description Type Required
confirmArgs The list of arguments to confirm. List<ConfirmArguments> 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)
  ...
  // Ensure that the identified argument has been provided by the user
  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)
  ...
  // Ensure that the identified argument has been provided by the user
  ensure(
    RequestArguments {arguments = [searchFlights.arguments.fromCity], response = cityPrompt},
  )

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

  ...

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

ensure()

Represents the requirement that the referenced action argument must be given a value. 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() action is the equivalent of a response() action with a Request response act paired with an expect() action.

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

Signature

action Nothing ensure(Args<RequestArguments> 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> Yes

Example 1

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

In this example, the ensure() action replaces the three pairs of response() 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() action in the previous example might result in three different prompts depending on which of the arguments don't have 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 it doesn't provide values for either. This can happen if both of the event type's 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() action for each referenced action argument that is required, you can use an ensure() 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()" action for the "startDate" argument, so the "ensure()" action will simulate interactions
  // in which the user is asked to provide the value for that argument
  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

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 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 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 request for the weather. Invoke is a RequestAct that indicates to Alexa Conversations that these utterances are a way the user might initiate the conversational flow to get the weather forecast.

namespace org.example.weather

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

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

// Describe the dialog flow
dialog Nothing GetWeatherDialog() {
  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

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 given 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()

Represents a skill response to the user. Returns Nothing.

Alexa Conversations interprets the response() 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() 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 Nothing response(Response response, ResponseAct act, ResponseAct nextAct = nothing, Thing payload = nothing)
Parameter Description Type Required
response The reference to the APL or APLA document to use. Response 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}?" Thing 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() 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 Nothing GetWeatherDialog() {
    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

utterances<T>()

Represents an utterance event. The given utterances represent variations of the utterances that trigger the event. Returns an UtteranceEvent.

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<String> 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<String> Yes

Example

In the following example, you provide the set of utterances to describe the WeatherEvent, which is then used to describe an expectation for that event in the dialog flow by using the expect() action. The strings contain references to the cityName property of the WeatherRequest type.

namespace org.example.weather

...

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

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

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

    ...
  }
}