Types in the Alexa Conversations Core Library

The Alexa Conversations Core Library (ACCL) provides a list of built-in types and actions 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 types when you use them in dialog samples.

Overview

The following table shows the types that ACCL provides.

Type Description
Action Represents a particular behavior of the skill, such as a verbal or visual response to the user, an AWS Lambda invocation, or a dialog management instruction (for example, to end the dialog).
Affirm Represents an Affirm request act, which conveys that Alexa Conversations should treat the event as an affirmation.
APL<T> Represents a reference to visual content that's displayed on Alexa devices with a screen, as an Alexa Presentation Language (APL) document.
APLA<T> Represents a reference to the speech that Alexa says to the user, as an APL for Audio (APLA) document.
Args<T> Represents a variable list of arguments in an action.
Argument<T> Represents an argument of an action.
Arguments<F : Function> Represents the arguments of a function, F.
Bye Represents a Bye response act, which you use to end the conversation.
CarryOverArgument Represents an argument that's passed from the previous action to the offered action.
ConfirmAction Represents a ConfirmAction response act, which you use before an action invocation to confirm that the user wants to invoke the action.
ConfirmArgs Represents a ConfirmArgs response act, which you use to confirm a list of action arguments that the user provided.
ConfirmArguments<T> Represents arguments to ask the user to confirm by using the confirmArgs<T> action.
Deny Represents a Deny request act, which conveys that Alexa Conversations should treat the event as a denial.
Dialog Represents a conversation between the user and Alexa.
Event<T> Represents a trigger, such as something the user says.
Function Represents the base type of all types that can be called.
Inform Represents an Inform request act, which conveys that Alexa Conversations should treat the event as information.
Invoke Represents an Invoke request act, which conveys that Alexa Conversations should treat the event as a user-initiated request to start the conversation flow.
List<T> Represents a list of items.
Locale Represents the name of a locale that the skill supports.
MultiModalResponse<T> Represents a reference to an APL document and, optionally, to an APLA document.
Nothing Represents the equivalent of null from many programming languages.
Notify Represents a Notify response act, which you use to inform the user of the result of an action, which is typically an API call.
Offer Represents an Offer response act, which you use to offer a related action when the user has achieved their initial goal.
Path Represents a path to a file.
ReqAlt Represents a ReqAlt response act, which you use to request an alternative response to continue the conversational flow.
ReqMore Represents a ReqMore response act, which you use to request to continue the conversational flow.
Request Represents a Request response act, which you use to request information from the user.
RequestAct Conveys to Alexa Conversations some additional information about an event, such as whether the event represents the initiation of a conversational flow, an affirmation to a previously returned question, a denial, and so on. The request act can be of type Affirm, Deny, Inform, or Invoke.
RequestArguments<T> Represents missing arguments to request.
Response<T> Represents a prompt from the skill to the user. Responses can be of type APL, APLA, or MultiModalResponse<T>.
ResponseAct Conveys to Alexa Conversations some additional information about a response, such as whether the response represents a request for the user to confirm an action, a suggestion to call a new action, and so on. The response act can be of type Bye, ConfirmAction, ConfirmArgs, Notify, Offer, ReqAlt, ReqMore, or Request.
SkillLevelResponses Represents responses that correspond to the responses that are built in to Alexa Conversations.
Type<T> Represents a type.
Utterance<T> Represents a user utterance.
UtteranceEvent<T> Represents an utterance event, which you define by using the utterances action.

For details about actions that use these types, see Actions in the ACCL.

Action

Represents a particular behavior of the skill, such as a verbal or visual response to the user, an AWS Lambda invocation, or a dialog management instruction (for example, to end the dialog). Extends Function.

For details about how to declare and use actions, see Use Actions in ACDL.

type Action : Function {
  Arguments arguments
  Type returnType
}
Field Description Type
arguments The arguments of the action. Arguments
returnType The return type of the action. Type

Affirm

Represents an Affirm request act, which conveys that Alexa Conversations should treat the event as an affirmation. Extends RequestAct.

type Affirm : RequestAct {}

APL<T>

Represents a reference to visual content that's displayed on Alexa devices with a screen, as an Alexa Presentation Language (APL) document. APL documents are imported from the <skill-directory>/skill-package/response/display/ folder in the skill package. For details, see Create APLA and APL files. Extends Response<T>.

type APL<T> : Response<T> {}

APLA<T>

Represents a reference to the speech that Alexa says to the user, as an APL for Audio (APLA) document. APLA documents are imported from the <skill-directory>/skill-package/response/prompts/ folder in the skill package. For details, see Create APLA and APL files. Extends Response<T>.

type APLA<T> : Response<T> {}

Args<T>

Represents a variable list of arguments in an action.

type Args<T> : List<T> {
}
Field Description Type
T The type of each argument. Type

Example

In the following example, anAction() accepts a variable set of arguments of type Number.

action Nothing anAction(Args<Number> numbers)
...
dialog ... {
  sample {
    ...

    anAction(1, 2, 3, 4)
  }
}

Argument<T>

Represents an argument of an action.

type Argument<T> {
  Type<T> argumentType
  Boolean isOptional
}

Field Description Type
argumentType The type of argument. Type<T>
isOptional Boolean that indicates whether the argument is optional. Boolean

Arguments<F : Function>

Represents the arguments of a function, F. This is an intrinsic type.

type Arguments <F : Function> {}

Bye

Represents a Bye response act, which you use to end the conversation. For details, see Bye. Extends ResponseAct.

type Bye : ResponseAct {
}

CarryOverArgument

Represents an argument that's passed from the previous action to the offered action. You offer an action by using the Offer response act.

type CarryOverArgument {
  Argument argument
  Thing source
}
Field Description Type
argument An argument that's passed from the previous action to the offered action. Argument
source The source of the carry-over argument. Thing

ConfirmAction

Represents a ConfirmAction response act, which you use before an action invocation to confirm that the user wants to invoke the action. For details, see ConfirmAction. Extends ResponseAct.

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

type ConfirmAction : ResponseAct {
  Action actionName
}
Field Description Type
actionName The action that Alexa requests the user to confirm. Action

ConfirmArgs

Represents a ConfirmArgs response act, which you use to confirm a list of action arguments that the user provided. For details, see ConfirmArgs. Extends ResponseAct.

For an alternative way to use the ConfirmArgs response act, see the confirmArgs<T>() action.

type ConfirmArgs : ResponseAct {
  List<Argument> arguments
}
Field Description Type
arguments The arguments that Alexa asks the user to confirm. List<Argument>

ConfirmArguments<T>

Represents arguments to ask the user to confirm by using the confirmArgs action.

type ConfirmArguments<T> {
  Response<T> response
  List<Argument<Thing>> arguments
}
Field Description Type
response The response that asks the user to confirm the arguments. Response<T>
arguments The arguments to ask the user to confirm. List<Argument<Thing>>

Deny

Represents a Deny request act, which conveys that Alexa Conversations should treat the event as a denial. Extends RequestAct.

type Deny : RequestAct {}

Dialog

Represents a conversation between the user and Alexa. Extends Function.

type Dialog : Function

Event<T>

Represents a trigger, such as something the user says.

type Event<T> {
  T entities
}
Field Description Type
entities The entities associated with the event. T

Function

Represents the base type of all types that can be called.

type Function

Inform

Represents an Inform request act, which conveys that Alexa Conversations should treat the event as information. Extends RequestAct.

type Inform : RequestAct {}

Invoke

Represents an Invoke request act, which conveys that Alexa Conversations should treat the event as a user-initiated request to start the conversation flow. Extends RequestAct.

type Invoke : RequestAct {}

List<T>

Represents a list of items. Alexa Conversations supports List expressions in actions and utterance sets.

type List<T> { }

Locale

Represents the name of a locale that the skill supports. You can access any supported locale as a property of the Locale enum. An example is Locale.en_US.

Possible values:

  • en_US
  • en_GB
  • en_AU
  • en_CA
  • en_IN
  • de_DE
  • es_US
  • ja_JP

MultiModalResponse<T>

Represents a reference to an APL document and, optionally, to an APLA document. For details, see Create APLA and APL files. Extends Response<T>.

type MultiModalResponse<T> : Response<T> {
  APLA<T> apla
  optional APL<T> apl
}
Field Description Type
apla The speech that Alexa says to the user, as APLA. APLA<T>
apl Optional visual content that Alexa displays on Alexa devices with a screen, as APL. APL<T>

Nothing

Represents the equivalent of null from many programming languages. This type is a bottom type – a subtype of everything. Nothing is a reserved keyword in ACDL.

type Nothing { }

Notify

Represents a Notify response act, which you use to inform the user of the result of an action, which is typically an API call. For details, see Notify. Extends ResponseAct.

type Notify : ResponseAct {
  Action actionName
  optional Boolean success
}
Field Description Type
actionName The action for which to report the results. Action
success Optional Boolean value that indicates whether the action was a success. Use true to indicate that the given action completed successfully. Use false if the action didn't complete successfully. Default: true. Boolean

Offer

Represents an Offer response act, which you use to offer a related action when the user has achieved their initial goal. For details, see Offer. Extends ResponseAct.

type Offer : ResponseAct {
  Action actionName
  optional List<Argument> requestArgs
  optional List<CarryOverArgument> carryOverArguments
}
Field Description Type
actionName The action to offer to the user. Action
requestArgs Optional list of arguments to request from the user. These arguments belong to the action to offer. List<Argument>
carryOverArguments Optional list of arguments that pass from the previous action to the offered action. List<CarryOverArgument>

Path

Represents a path to a file.

type Path : String {}

ReqAlt

Represents a ReqAlt response act, which you use to request an alternative response to continue the conversational flow. For details, see ReqAlt. Extends ResponseAct.

type ReqAlt : ResponseAct {
  List<Argument> arguments
}
Field Description Type
arguments The alternative arguments. List<Argument>

ReqMore

Represents a ReqMore response act, which you use to request to continue the conversational flow. For details, see ReqMore. Extends ResponseAct.

type ReqMore : ResponseAct {
}

Request

Represents a Request response act, which you use to request information from the user. For details, see Request. Extends ResponseAct.

type Request : ResponseAct {
  List<Argument> arguments
}
Field Description Type
arguments A list of arguments to request. List<Argument>

RequestAct

Conveys to Alexa Conversations some additional information about an event, such as whether the event represents the initiation of a conversational flow, an affirmation to a previously returned question, a denial, and so on.

For details about using request acts, see Request Acts in the ACCL.

You can't define your own request acts. Alexa Conversations rejects custom request acts that extend RequestAct.

type RequestAct { }

The request act can be one of the following types:

RequestArguments<T>

Represents missing arguments to request.

type RequestArguments<T> {
  List<Argument<Thing>> arguments
  Response<T> response
  optional Event<Thing> informEvent
}

Field Description Type
arguments The missing arguments to request. List<Argument<Thing>>
response The response that requests the missing arguments. Response<T>
informEvent The optional event in which the user provides the missing arguments. Event<Thing>

Response<T>

Represents a prompt from the skill to the user. Responses can be of type APL, APLA, or MultiModalResponse. You provide APL, APLA, and MultiModalResponse expressions to response-related actions, such as response<T>(). For details about using responses, see Use Responses in ACDL.

type Response<T> {}

ResponseAct

Conveys to Alexa Conversations some additional information about a response, such as whether the response represents a request for the user to confirm an action, a suggestion to call a new action, and so on. You associate responses with response acts. To associate a response with a response act, you pass the response<T>() action an expression that derives from ResponseAct.

For details, see Response Acts in the Alexa Conversations Core Library (ACCL).

type ResponseAct {}

The response act can be one of the following types:

SkillLevelResponses

Represents responses that correspond to the responses that are built in to Alexa Conversations.

type SkillLevelResponses {
  Response welcome,
  Response out_of_domain,
  Response bye,
  Response reqmore,
  Response provide_help,
  Optional<Response> thank_you,
  Optional<Response> you_are_welcome,
  Optional<Response> notify_failure
}
Field Description Type
welcome The response that corresponds to the built-in welcome response. Response
out_of_domain The response that corresponds to the built-in out_of_domain response. Response
bye The response that corresponds to the built-in bye response. Response
reqmore The response that corresponds to the built-in reqmore response. Response
provide_help The response that corresponds to the built-in provide_help response. Response
thank_you The response that corresponds to the built-in thank_you response. Optional<Response>
you_are_welcome The response that corresponds to the built-in you_are_welcome response. Optional<Response>
notify_failure The response that corresponds to the built-in notify_failure response. Optional<Response>

Type<T>

Represents a type.

type Type<T> {}

Utterance<T>

Represents a user utterance.

type Utterance<T> : String

UtteranceEvent<T>

Represents an utterance event, which you define by using the utterances action. Extends Event.

type UtteranceEvent<T> : Event<T> {
  String text
}
Field Description Type
text The utterances associated with the utterance event. String