Message Flow

Alexa sends your skill directives that request something on behalf of the customer. You provide code that responds to directives with events. Your code is hosted as a Lambda function on AWS
Lambda (a service offering by Amazon Web
Services) When you respond to a directive, you can:

Reply synchronously with an Alexa.Response event or an error message event from your Lambda function in 8 seconds or less.

Reply asynchronously with an Alexa.Response event or an error message event to the Alexa event gateway in 8 seconds or less. Note that asynchronous replies are not supported for all interfaces, and this is noted in the interface topics.

A string that specifies the category for the message payload. This aligns to the capability interface that contains that directive. For example:

Alexa.PowerController

Alexa.ThermostatController

name

The name of the directive such as TurnOn or TurnOff

messageId

A unique identifier for a single request or response. This is used for tracking purposes and your skill should log this information, although it should not be used to support business logic. Every message must have this field populated. Any string of alphanumeric characters and dashes less than 128 characters is valid, but a version 4 UUID, which is a UUID generated from random numbers, is recommended.

correlationToken

A token that identifies a directive and one or more events associated with it. A correlation token is included in the following message types:

A directive from Alexa to the skill.

An event in response to a directive.

A response event for a directive request must include the same correlation.
If the event is not in response to a request from Alexa, a correlation token must not be provided.

payloadVersion

The version of the capability interface applied to this message.

Endpoint object

An endpoint object identifies the target for a directive and the origin of an event. An endpoint can represent one of the following:

Physical device

Virtual device

Group or cluster of devices

Software component

In addition, the endpoint contains an authentication token.

For a directive, the token enables the communication with the device(s) or component represented by the endpoint.

For an event, the token is only required for events sent to the Alexa event gateway.

Following is an example JSON for a typical message endpoint:

"endpoint":{"scope":{"type":"BearerToken","token":"Alexa-access-token"},"endpointId":"the identifier of the target endpoint","cookie":{"key1":"some information","key":"value pairs received during discovery"}},

An endpoint object will contain the following properties.

Property

Description

scope

A polymorphic object that describes an aspect of the authentication granted to the message exchange. See scope object for more information.

endpointId

A unique identifier. The identifier must be unique across all endpoints for a customer within the domain of the skill. This identifier is provided initially during device discovery, and should consistently identify this device associated with this user.

cookie

A list of key/value pairs associated with the endpoint. These are provided during discovery and are sent in each message for an endpoint.

Scope object

A scope is a polymorphic object that provides authorization and identifying info for this message. A scope contains a type field and an additional key/value pair that vary depending on the type. The following table describes the current types that are supported.

BearerToken scope

Provides an OAuth bearer token for accessing a linked customer account or identifying an Alexa customer. Typically used for Smart Home Skills.

Field

Description

Type

Required

token

The token to validate a customer in the system they account-linked when they enabled the skill.

String

Yes

BearerToken example

"scope":{"type":"BearerToken","token":"Alexa-access-token"}

BearerTokenWithPartition scope

Provides an OAuth bearer token for accessing a linked customer account and the physical location where the discovery request should be applied. Typically used for skills that target Alexa for Business.
When the scope type is BearerTokenWithPartition, you will see the following fields.

Field

Description

Type

Required

token

The token for identifying and accessing a linked customer account.

String

Yes

partition

The location target for the request such as a room name or number.

String

Yes

userId

A unique identifier for the user who made the request. You should not rely on userId for identification of a customer. Use token instead.

In an event message, the scope optionally contains a token that identifies a customer to Alexa, which is obtained through the permission process with Login with Amazon (LWA). This token is required for messages to the Alexa event gateway. For more information, see Authenticating a Customer to Alexa with Permissions.

Context object

Use the Context object to report the state of an endpoint in any event message. A context contains an array of reportable properties objects and their state. When you send a response event with context, you should ensure that the values reported incorporate all the side-effects from handling the directive. In other words, the property values reported must be after any value-changing side effects of handling the directive.

For more details about the context object and state reporting, see State Reporting for more information about the structure of properties, see Property Schemas.

The time at which the property value was sampled in ISO 8601 format, and specified in UTC. Example: "YYYY-MM-DDThh:mm:ss.sD"

uncertaintyInMilliseconds

Indicates the uncertainty of the reported property in milliseconds of elapsed time since the property value was possibly retrieved. For example, if you obtain this value by polling a hardware device every 60 seconds, then the uncertainty in the time of the sampled value would be 60000 in milliseconds.

Payload object

The payload for a message can vary depending on what type of message it is.
The next few sections describe messages by functional area.

Discovery Messages

This interface describes messages to identify the device and capabilities available to
this skill adapter.

State and Change Reporting Messages

These messages are sent to request the state of interface properties, respond to state requests, send change reports or signal Alexa that a response will come later to the event gateway. These messages are formatted the same way regardless of the interface of the request directive.

Percentage Messages

This interface describes messages to set, increment or decrement a endpoint by a percentage. These are generic percentages messages, and if possible, you should always use a more specific message type, such as BrightnessController for a light.

Smart Camera Messages

This interface describes messages to query a camera and return a stream URI. For more information and technical requirements for building a smart home skill for cameras, see Build Smart Home Skills for Cameras.

Entertainment Control Messages

These interfaces describe messages to enable you to interact with entertainment devices and respond to requests for changing the channel of a device, changing the playback of content, or increasing the playback volume.
For more information, see Build Smart Home Skills for Entertainment Devices.