Response Acts in the Alexa Conversations Core Library

In the Alexa Conversations Description Language (ACDL), you associate responses with response acts. Response acts convey to Alexa Conversations some additional information about a response. For example, response acts convey whether the response represents a request for the user to confirm an action, a suggestion to call a new action, and so on.

For example, the Notify response act signifies that the response is an outcome of an action ("In Seattle, it's 65 degrees.") The Request response act signifies that the response is asking the user for information that an action requires "What city?").

To associate a response with a response act, you pass the response<T>() action an expression that derives from ResponseAct. For details about how to use response acts in response definitions, see Use Responses in ACDL.

Syntax

You use response acts when you define a response<T>() action as follows.

action Nothing response(Response response, ResponseAct act, ResponseAct nextAct = nothing, Thing payload = nothing)

The response<T>() action, which is from the Alexa Conversations Core Library (ACCL), accepts one or more ResponseAct arguments. The ResponseAct argument can be one of the following values:

The examples on this page reference the following actions.

action SearchFlightResult searchFlights(City fromCity, City toCity, Date startDate, Date returnDate = nothing)
action BookFlightResult bookFlight(SearchFlightResult searchResult)

Bye

You use the Bye response act to end the conversation. For example, the associated Alexa speech might be, "Thanks for using Weather Bot. Goodbye."

To inform the user of the result of the current action and end the conversation, you can chain the Bye response act with the Notify response act. For details, see Notify and Bye.

Type declaration:

type Bye : ResponseAct {
}

Example:
The following example shows how to use the Bye response act with the response<T>() action.

sample {
  // "Thanks for using Weather Bot. Goodbye."
  response(byePrompt, Bye {})
}

ConfirmAction

You use the ConfirmAction response act before an action to confirm that the user wants to invoke the action. For example, the associated Alexa speech might be, "You'd like to know the weather for Seattle, right?"

For an alternative way to use the ConfirmAction response act, you can use the confirmAction<T>() action.

Type declaration:

type ConfirmAction : ResponseAct {
  Action actionName
}

Example:
The following example shows how to use the ConfirmAction response act with the response<T>() action.

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

The payload argument in ConfirmAction

You must explicitly define the payload argument for ConfirmAction. The payload property names must be among the arguments of the action that is confirmed.

The following examples show valid ways to specify the payload for ConfirmAction.

// These are valid examples, assuming that searchFlights is an API with fromCity, toCity, and startDate as arguments. Any combination of the arguments is valid.

response(confirmSearchFlightsPrompt, ConfirmAction {actionName = searchFlights}, payload = nothing)

response(confirmSearchFlightsPrompt, ConfirmAction {actionName = searchFlights}, payload = FromCityType {fromCity = bookFlightRequest.fromCity})

response(confirmSearchFlightsPrompt, ConfirmAction {actionName = searchFlights}, payload = ToCityType {toCity = bookFlightRequest.toCity}) 

response(confirmSearchFlightsPrompt, ConfirmAction {actionName = searchFlights}, payload = StartDateAndToCityType {startDate = bookFlightRequest.startDate, toCity = bookFlightRequest.toCity})

The following example of ConfirmAction is invalid because the payload contains a property that's not an argument of the action to be confirmed.

// Invalid example
response(confirmSearchFlightsPrompt, ConfirmAction {actionName = searchFlights}, payload = ReturnDateType {returnDate = bookFlightRequest.returnDate})

ConfirmArgs

You use the ConfirmArgs response act to confirm action arguments that the user provided. For example, the associated Alexa speech might be, "That was for Seattle?"

If you use the ConfirmArgs response act for an argument, you must have a corresponding expect() action that provides that specific argument. Alternatively, you can provide an ensure<T>() action, which represents a response<T>() action plus the expect() action.

For an alternative way to use the ConfirmArgs response act, see the confirmArgs<T>() action in the Alexa Conversations Core Library (ACCL).

Type declaration:

type ConfirmArgs : ResponseAct {
  List<Argument> arguments
}

Example:
In the following example, the skill responds to the user with a prompt to confirm the invocation of the bookFlight() action.

sample {
  bookFlightRequest = expect(Invoke, bookFlightEvent)
  ...
  // Ensure that the identified argument has been provided by the user
  ensure(
    {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)
}

If you use the ConfirmArgs response act as an argument, you must provide a corresponding Request response act for the argument, either with the response<T>() action and the Request response act or with the ensure<T>() action.

Therefore, the previous example includes an ensure<T>() action with the fromCity, toCity, and startDate arguments. Alternatively, you can provide response<T>() actions with the Request response act for each argument. You can swap them out for each other, as shown in Request multiple arguments in one response<T>() action.

The payload argument in ConfirmArgs

You must explicitly define the payload argument for ConfirmArgs. The payload property names must match arguments that the ConfirmArgs response act uses.

The following examples show valid ways to specify the payload for ConfirmArgs.

// Valid examples

response(confirmFromCityPrompt, ConfirmArgs {arguments = [searchFlights.arguments.fromCity]}, payload = FromCityType {fromCity = bookFlightRequest.fromCity})

response(confirmToCityPrompt, ConfirmArgs {arguments = [searchFlights.arguments.toCity]}, payload = ToCityType {toCity = bookFlightRequest.toCity})

response(confirmDatePrompt, ConfirmArgs {arguments = [searchFlights.arguments.startDate]}, payload = StartDateType{startDate = bookFlightRequest.startDate})

The following examples are invalid because ConfirmArgs has a missing or mismatched payload.

// Invalid due to missing payload
response(confirmFromCityPrompt, ConfirmArgs {arguments = [searchFlights.arguments.fromCity]}) 

// Invalid due to missing payload
response(confirmToCityPrompt, ConfirmArgs {arguments = [searchFlights.arguments.toCity]}, payload = EmptyPayloadType {}) 

// Invalid due to mismatched payload
response(confirmDatePrompt, ConfirmArgs {arguments = [searchFlights.arguments.startDate]}, payload = ToCityType {toCity = bookFlightRequest.toCity}) 

// Invalid due to mismatched payload
response(confirmDatePrompt, ConfirmArgs {arguments = [searchFlights.arguments.startDate]}, payload = StartDateAndToCityType {startDate = bookFlightRequest.startDate, toCity = bookFlightRequest.toCity})

Using the ConfirmArgs payload arguments in responses

The APL/APLA documents can use the payload arguments specified by ConfirmArgs. In the previous valid example of how to use ConfirmArgs, there are three prompts (one for each response<T>() action). The following example shows the corresponding three content lines. Each line is spliced from its example APLA document to demonstrate how the payload argument can access the information provided in the dialog sample.

// Taken from confirmFromCityPrompt document
"content": "Just to confirm, you want to book a flight from ${payload.fromCity}?"

// Taken from confirmToCityPrompt document
"content": "Just to confirm, you want to book a flight to ${payload.toCity}?"

// Taken from confirmDatePrompt document
"content": "Just to confirm, you want to book a flight on ${payload.startDate}?"

Notify

You use the Notify response act to inform the user of the result of an action, which is typically an API call. For example, the associated Alexa speech might be, "The weather in Seattle is 65 degrees." You typically precede the Notify() action with an action invocation. The default of success is true, so specifying success is optional for the successful case.

Type declaration:

type Notify : ResponseAct {
  Action actionName
  optional Boolean success
}

Example:
The following example shows how to use the Notify response act with the response<T>() action.

sample {
  ...
  searchFlightResult = searchFlights(bookFlightRequest.fromCity, bookFlightRequest.toCity, bookFlightRequest.startDate)

  // "Your flight from Seattle to Portland on July 31st has been booked"
  response(
    notifyFlightResponse,
    Notify {actionName = searchFlights, success = true},
    payload = FlightResultPayload {searchResult = searchFlightResult})
}

Offer

You use the Offer response act to offer a related action when the user has achieved their initial goal. For example, the associated Alexa speech might be, "Would you like the hour-by-hour forecast?"

To inform the user of the result of the current action and provide an offer, you can chain the Offer response act with the Notify response act. For details, see Notify and Offer.

Type declaration:

type Offer : ResponseAct {
  Action actionName
  optional List<Argument> requestArgs
  optional List<CarryOverArgument> carryOverArguments
}

Example:
The following example shows how to use the Offer response act with the response<T>() action.

sample {
  ...
  // sample: "Do you want to book a return flight from Portland?"
  response (
    offerReturnFlight,
    Offer {actionName = searchFlights},
    payload = OfferReturnFlightPayload { destination = req.toCity } )
  ...
}

ReqAlt

You use the ReqAlt response act to request an alternative response to continue the conversational flow. For example, the associated Alexa speech might be, "Would you like to know the weather for a different city?" You can't use the ReqAlt response act as a standalone response act in a response<T>() action.

To inform the user that Alexa was unable to fulfill the goal with the provided arguments and then request alternative values for the arguments, you can chain the ReqAlt response act with the Notify response act. For details, see Notify and ReqAlt.

Type declaration:

type ReqAlt : ResponseAct {
  optional
}

ReqMore

You use the ReqMore response act to request to continue the conversational flow after the completion or interruption of an initial goal. For example, the associated Alexa speech might be, "Is there anything else I can do for you?"

To inform the user of the result of the current action and request another goal, you can chain the ReqMore response act with the Notify response act. For details, see Notify and ReqMore.

Type declaration:

type ReqMore : ResponseAct {
}

Example:
The following example shows how to use the ReqMore response act such that the skill responds to the user asking for another goal.

sample {
  ...
  response(
    successPrompt,
    Notify { action = searchFlights, success = true })

  // "What else can I do?"
  response(
    requestMorePrompt,
    ReqMore {})
  ...
}

Request

You use the Request response act to request the user for missing arguments that an action requires. For example, the associated Alexa speech might be, "Which city?"

A Request expression passed to the response<T>() action indicates to Alexa Conversations that the skill should ask the user for information that the skill needs to invoke an action. The Request expression identifies the arguments for which the request is made.

Type declaration:

type Request : ResponseAct {
  List<Argument> arguments
}

The Alexa Conversations simulator requires that each required argument of an action must be given a value. You can extract the value for an argument from an event by using the expect() action. However, some events might not produce a value for the required argument. For example, the argument value isn't extracted from the utterance or the argument is declared to be optional. In these cases, the skill must ask the user to provide the required value. You represent this request by using a Request response act expression with a response<T>() action.

If the value to be passed to the desired action is the result of a previous invocation of an action and the argument isn't declared to be optional, there's no need to ask the user to provide it.

In the following example, the event doesn't produce any of the required arguments for the searchFlights() action, so the skill should ask the user. You can also use the ensure<T>() action to represent this example with fewer lines.

sample {
  // "Book a flight for me"
  req = expect(Invoke, bookFlightEvent)

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

  // "From Seattle"
  expect(Inform, informCityEvent)

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

  // "To Portland"
  expect(Inform, informCityEvent)

  // "On which date?"
  response(response = datePrompt, act = Request {arguments = [searchFlights.arguments.startDate]})

  // "On July 31st"
  expect(Inform, informDateEvent)

  // Invoke action
  searchFlightResult = searchFlights(req.fromCity, req.toCity, req.startDate)

  ...
}

Provide all of the request actions explicitly

The following dialog sample uses a separate response<T>() action for each of the required arguments. The searchFlights() action has three required arguments (fromCity, toCity, and startDate), and each of these arguments is covered by a Request response act.

sample {
  // "Book a flight for me"
  expect(Invoke, bookFlightEvent)

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

  // "From Seattle"
  fromCity = expect(Inform, informCityEvent)

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

  // "To Portland"
  toCity = expect(Inform, informCityEvent)

  // "On which date?"
  response(response = datePrompt, act = Request {arguments = searchFlights.arguments.startDate]})

  // "On July 31st"
  startDate = expect(Inform, informDateEvent)

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

The following dialog sample in which the user provides all of the required information in the opening sentence. The sample still requires Request response acts for each required argument. However, instead of using the response<T>() action, the sample uses the ensure<T>() action from the ACCL. For details, see ensure<T>().

sample {
  // "Book a flight from Seattle to Portland on July 31st"
  bookFlightRequest = expect(Invoke, bookFlightEvent)
  ensure(
    {arguments = [searchFlights.arguments.fromCity], response = fromCityPrompt},
    {arguments = [searchFlights.arguments.toCity], response = toCityPrompt},
    {arguments = [searchFlights.arguments.startDate], response = datePrompt}
  )
  searchFlightResult = searchFlights(bookFlightRequest.fromCity, bookFlightRequest.toCity, bookFlightRequest.startDate)
  ...
}

Request multiple arguments in one response() action

You can request multiple arguments of the same action in a single response<T>() action.

However, this technique doesn't fulfill the requirement of having a separate response<T>() action for each required argument. To cover multiple arguments using one response<T>() action, you must either use additional standalone response<T>() actions for each required argument, or an ensure<T>() action that includes all of the arguments.

The following example uses the ensure<T>() action to request multiple arguments in one response<T>() action.

// Using the ensure<T>() action
sample {
  expect(Invoke, bookFlightEvent)

  // Multiple arguments of the same action (searchFlights) can be requested in a single expression
  // "From which city and to which city?"
  response(response = toAndFromCityPrompt, act = Request {arguments = [searchFlights.arguments.fromCity, searchFlights.arguments.toCity]})

  // The requirement of having a separate response<T>() action for each required argument can be fulfilled
  // using the ensure<T>() action
  ensure(
    {arguments = [searchFlights.arguments.fromCity], response = fromCityPrompt},
    {arguments = [searchFlights.arguments.toCity], response = toCityPrompt}
  )

  // "From Seattle to Portland"
  toAndFromCityResponse = expect(Inform, informToAndFromCityEvent)
  response(response = datePrompt, act = Request {arguments = [searchFlights.arguments.startDate]})
  startDate = expect(Inform, informDateEvent)
  searchFlightResult = searchFlights(toAndFromCityResponse.fromCity, toAndFromCityResponse.toCity, startDate.date)
    ...
}

The following example uses individual response<T>() actions to request multiple arguments in one response<T>() action.

// Use individual response<T>() actions
sample {
  expect(Invoke, bookFlightEvent)

  // Multiple arguments are being requested at once here
  // "From which city and to which city?"
  response(response = toAndFromCityPrompt, act = Request {arguments = [searchFlights.arguments.fromCity, searchFlights.arguments.toCity]})

  // The requirement of having a separate response<T>() action for each required argument can also be fulfilled
  // using individual response<T>() action expressions
  response(response = fromCityPrompt, act = Request {arguments = [searchFlights.arguments.fromCity]})
  response(response = toCityPrompt, act = Request {arguments = [searchFlights.arguments.toCity]})

  // "From Seattle to Portland"
  toAndFromCityResponse = expect(Inform, informToAndFromCityEvent)
  response(response = datePrompt, act = Request {arguments = [searchFlights.arguments.startDate]})
  startDate = expect(Inform, informDateEvent)
  searchFlightResult = searchFlights(toAndFromCityResponse.fromCity, toAndFromCityResponse.toCity, startDate.date)
  ...
}

Cross reference between response acts and dialog acts

If you develop Alexa Conversations skills by using the developer console, you're familiar with the concept of Alexa response dialog acts. Alexa response dialog acts help Alexa Conversations identify the purpose of Alexa responses within the flow of a dialog. With the ACCL, you specify Alexa response dialog acts by using response acts.

Alexa response dialog acts indicate the purpose of the Alexa response. The following table shows the response act that corresponds to each Alexa response dialog act.

Dialog act Response act Description

API Failure

Notify

Alexa is notifying the user that the API call was unsuccessful.

Example: "Weather data for Seattle is not available."

API Success

Notify

Alexa is notifying the user that the API call was successful.

Example: "The weather in Seattle is 65 degrees."

Confirm API

ConfirmAction

Alexa is confirming or denying with the user all required API arguments and optional API arguments (any number) that belong to an API definition.

Example: "You want the weather for Seattle, right?"

Confirm Args

ConfirmArgs

Alexa is confirming or denying arguments that the user provided.

Example: "That was for Seattle?"

Offer Next API

Offer

Alexa is offering the user a related action when the user has achieved their initial goal.

Example: (Chained with dialog act API Success) "The weather in Seattle is 65 degrees. Would you like the hour-by-hour forecast?"

Request Alt

ReqAlt

Alexa is requesting alternative values for the arguments.

Example: (Chained with dialog act API Success) "The weather in Seattle is 65 degrees. Would you like to know the weather for a different city?"

Request

Request

Alexa is requesting missing arguments that are required for invoking an action.

Example: "Which city?"
Was this page helpful?

Last updated: Nov 27, 2023