Alexa Interface Message Guide

When you create an Alexa skill and implement Alexa interfaces in your skill code, you send messages to and receive messages from Alexa. Alexa sends directives to your skill to request something on behalf of the user user. If your skill controls a device, Alexa can send directives to control the device, or to request state information about the device. You respond to directives by sending events to Alexa. You can also send events to Alexa proactively.

Messages from Alexa to your skill

The following list includes messages that Alexa sends to your skill:

  • AcceptGrant directive – Alexa gives you credentials that identify and authenticate a user to Alexa.
  • Discover directive – A user wants to connect their device to your smart home skill.
  • ReportState directive – Alexa wants to announce or display the state of a device connected to your smart home skill.
  • Interface-specific directives – A user wants to control their smart home device. For examples of directives, see the documentation for each interface.

Messages from your skill to Alexa

The following list includes event messages that your skill sends to Alexa:

  • AcceptGrant.Response event – You send an accept grant response event after you successfully receive and store credentials for a user.
  • Discover.Response event – You send discover responses so that users can connect their devices to your smart home skill.
  • AddOrUpdateReport event – You send add or update reports when a user adds or updates a device connected to your smart home skill.
  • DeleteReport event – You send delete reports when a user deletes a device connected to your smart home skill.
  • StateReport event – You send state reports to respond to report state directives.
  • ChangeReport event – You send change reports to proactively report when the state of a device changes.
  • Response event – You send response events to respond to interface-specific directives.
  • DeferredResponse event – You send a deferred response event after certain directives to notify Alexa that your actual response will come later.
  • ErrorResponse event – You send error response events to respond to interface-specific directives when you can handle the directive successfully. For example if you receive a turn on directive, but the device is not plugged in.

Examples of all events that you send to Alexa are provided in the documentation for each interface.

Common message fields

Header object

The JSON for each message contains a header object.

Header object example

Copied to clipboard.

"header": {
  "namespace": "Alexa",
  "name": "Response",
  "messageId": "<message id>",
  "correlationToken": "<an opaque correlation token>",
  "payloadVersion": "3"
}

Header object details

Property Description Required
namespace The namespace and interface for the operation in the message. For example, Alexa, Alexa.Discovery, Alexa.PowerController, and others. Yes
name The name of the operation in the message. For example Discover, ReportState, TurnOn, AdjustPercentage, Response, ErrorResponse, StateReport, ChangeReport, and others. Yes
messageId A unique identifier for each message. The message ID is used for tracking purposes. You should log the message ID, but don't use the message ID to program business logic. Any string of alphanumeric characters and dashes of fewer than 128 characters is valid, but a version 4 UUID, which is a UUID generated from random numbers, is recommended. Yes
correlationToken If a message you receive from Alexa includes a correlation token, include the correlation token in your response message. When you send a response asynchronously to the Alexa event gateway you must include the same correlation token that you received from Alexa. When you send a proactive message to the Alexa event gateway you must include a correlation token that you create. No
payloadVersion The version of the interface specified in the namespace field. Yes

Endpoint object

If your skill controls a device, messages from and to Alexa contain an endpoint object. For details about the endpoint object in a discovery response, see the endpoint object.

The Alexa.Response message and the ChangeReport event include an endpoint object to help Alexa identify the endpoint and authenticate your skill.

Property Description Type

endpointId

Identifies the endpoint.

String

scope

A BearerToken type scope to authenticate the skill.

A Scope object

Scope object

The scope object provides authorization and identifying info for a message. The scope object can appear in the payload, for example in the discover directive, or in an endpoint object, for example in some response messages.

The scope object is required for messages that you send to the the Alexa event gateway.

BearerToken scope

The BearerToken scope provides an OAuth bearer token for accessing a linked user account or identifying an Alexa user. Typically used for smart home skills.

BearerToken example

Copied to clipboard.

"scope": {
  "type": "BearerToken",
  "token": "<an OAuth2 bearer token>"
}

BearerToken details

Property Description Required
token The token to validate a user in the system they account-linked when they enabled the skill. Yes

BearerTokenWithPartition scope

The BearerTokenWithPartition scope provides an OAuth bearer token for accessing a linked user account and specifying a physical location. Typically used for skills that target Alexa for Business.

BearerTokenWithPartition example

Copied to clipboard.

"scope": {
  "type": "BearerTokenWithPartition",
  "token": "<an OAuth2 bearer token>",
  "partition": "<partition, for example, room101>",
  "userId": "<user id>"
}

BearerTokenWithPartition details

Property Description Required
token The token for identifying and accessing a linked user account. Yes
partition The location target for the request such as a room name or number. Yes
userId A unique identifier for the user who made the request. Don't rely on userId to identify users, use token instead. Yes