Alexa Interface Message and Property Reference

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. 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 responses to Alexa. You can also send events to Alexa proactively.

This references includes the list of foundational messages and parameters that all skill implement.

Message reference

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 the user to Alexa.
  • Discover directive – The user asks Alexa 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 or video skill.
  • Interface-specific directives – The user asks Alexa to control their 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 – After you successfully receive and store credentials for the user, you send an accept grant response.
  • Discover.Response – You send discover responses so that users can connect their devices to your skill.
  • AddOrUpdateReport event – After the user adds or updates a device connected to your skill, you send the event to let Alexa know about the new or updated device.
  • DeleteReport event – After the user deletes a device connected to your smart home skill, you send the event to to let Alexa know.
  • StateReport – You send state reports to respond to report state directives to let Alexa know the state of the devices that your skill controls.
  • ChangeReport event – You send change report events to proactively report when the state of a device changes.
  • Response event – You send responses to interface-specific directives.
  • DeferredResponse event – You send a deferred response event after certain directives to notify Alexa that your actual response comes later.
  • ErrorResponse – If you can't handle interface-specific directives successfully, you send error responses to indicate the failure reason. For example, if you receive a turn on directive, but the device isn't plugged in.

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

Message format

All directives, events, and responses share the same message contents:

  • Header — Defines the message and the interface.
  • Endpoint — Identifies the device and includes authentication information.
  • Payload — Message parameters. Contents of the payload vary based on the interface defined in the header.

For directives, these properties are part of the Directive object. For events and responses, these properties are part of the Event object. In addition, some events and responses contain the Context object.

The following example shows a directive request. The message includes the header, endpoint, and payload objects.

{
    "directive": {
        "header": {
            "namespace": "Alexa.PowerController",
            "name": "TurnOn",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 bearer token"
            },
            "endpointId": "endpoint id",
            "cookie": {}
        },
        "payload": {}
    }
}

The following example shows a directive response. The message includes the header, endpoint, payload, and context objects.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 bearer token"
            },
            "endpointId": "endpoint ID"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
        }]
    }
}

Property reference

The following properties are the same across all message types.

Header object

The following table shows the properties that you include in the Header object.

Property Description Type Required

namespace

Identifies the interface of the message payload. For example, Alexa, Alexa.Discovery, Alexa.PowerController.

String

Yes

name

Name of the directive, event, or response in the message. For example Discover, ReportState, TurnOn, AdjustPercentage, Response, ErrorResponse, StateReport, ChangeReport.

String

Yes

messageId

A unique identifier for each message. Include a new value in every response and event that your skill sends. Amazon recommends using a version 4 UUID.
Valid value: String of alphanumeric characters and dashes up to 128 characters.
Use for tracking purposes. You can log the message ID, but don't use the message ID to program business logic.

String

Yes

correlationToken

Opaque token that identifies the message exchange. If you receive a directive from Alexa that includes a correlation token, include the same correlation token in your response message. When you send a response asynchronously to the Alexa event gateway, you also include the correlation token that you received from Alexa. If you send an event that isn't in response to a request from Alexa, don't include the correlation token. For example, you don't include a correlationToken when you send an Alexa.ChangeReport event.

String

No

payloadVersion

API version of the interface specified in the namespace field.
Valid value: "3"

String

Yes

Endpoint object

If your skill controls a device, messages from and to Alexa contain an Endpoint object. Messages from your skill to Alexa include an Endpoint object to help Alexa identify the device and authenticate your skill. For details about the definition of the Endpoint object in a discovery response, see the endpoint object.

The following table shows the properties included in the Endpoint object.

Property Description Type Required

endpointId

Identifies the device associated with the user. The identifier must be unique across all devices owned by the user within the domain of the skill. You provide the endpointID during discovery, and you must use the same identifier consistently in all messages that target the same device.
Valid values: String of alphanumeric characters up to 256 characters. Can include letters, numbers, spaces, and the following special characters: _ - = # ; : ? @ &.

String

Yes

scope

Bearer token scope to authenticate the skill. Required for events and asynchronous responses sent to the Alexa gateway.

Scope object

No

cookie

List of key-value pairs associated with the endpoint. You provide the cookies during discovery and Alexa returns them in each message to your skill for the endpoint.
Valid values: Up to 5000 bytes

List of JSON-formatted strings

No

Scope object

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

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

The following table shows the properties included in the Scope object.

Property Description Type Required

type

Provides the scope type of the OAuth token.
Valid values: BearerToken, BearerTokenWithPartition

String

Yes

token

OAuth bearer token to identify and access a linked customer account.

String

Yes

partition

Location target for the request, such as a room name or number.
Valid for BearerTokenWithPartition only.

String

No

userId

Unique identifier for the user who made the request. Don't rely on this value to identify users. Use token instead.
Valid for BearerTokenWithPartition only.

String

No

BearerToken scope

The BearerToken scope type provides an OAuth bearer token for accessing a linked customer account or identifying an Alexa customer. You receive the token during authentication. Typically used for smart home and video skills.

The following example shows a BearerToken scope.

Copied to clipboard.

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

The BearerTokenWithPartition scope type 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.

The following example shows a BearerTokenWithPartition scope.

Copied to clipboard.

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

Directive object

All directives include the Directive object.

Property Description Type Required

header

Identifies the message and interface.

Header object

Yes

endpoint

Identifies the endpoint that the user wants to control and provides authorization to authenticate Alexa.

Endpoint object

Yes

payload

Identifies properties that are part of the directive.

Payload object

Yes

Event object

All events and responses to directives include the Event object.

Property Description Type Required

header

Identifies the message and interface.

Header object

Yes

endpoint

Identifies the endpoint and provides authorization to authenticate your skill.

Endpoint object

Yes

payload

Identifies the properties required in the response. The payload varies for each directive, response, and event. For details about the payload properties, see the interface for your device.
If the message doesn't include a payload, set to an empty object.

Object

Yes

Context object

The Context object contains a list all reportable properties of the endpoint. To include a property, you must define the property as retrievable = true in your discovery response. Amazon recommends that you specify the state of all the properties of the endpoint, including the properties that didn't change.

Property Description Type Required

properties

Identifies the retrievable properties of the endpoint. Include one Property object for each property reported.

Array of Property objects

No

Payload object

The payload varies for each directive, response, and event. For details about the payload properties, see the interface documentation for each interface that your device supports.

Property object

The Property object defines a reportable property of the endpoint. Each Alexa interface defines the property name and value. For details, see the documentation for each interface that you support in your Alexa skill.

    "properties": [{
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2021-11-15T14:20:00Z",
            "uncertaintyInMilliseconds": 0
        },
        {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
                "value": "OK"
            },
            "timeOfSample": "2021-11-15T14:20:00Z",
            "uncertaintyInMilliseconds": 0
        }
    ]

The following table shows the Property object parameters.

Property Description Type Required

namespace

Name of the Alexa capability interface to which the property belongs, such as, Alexa.PowerController.

String

Yes

instance

Name of the interface instance that you defined in the discovery response. For generic controller interfaces only. For example, Dryer.Temperature.

String

No

name

Name of the reported property that belongs to the namespace.

String

Yes

value

Value of the reported property. Each Alexa interface defines the type of the value field.

Various

Yes

timeOfSample

Time the endpoint detected the state change.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

Yes

uncertaintyInMilliseconds

Uncertainty of the timeOfSample field in milliseconds.
This field represents the number of milliseconds after the endpoint last confirmed the property value. For example, if the endpoint sampled the property value 60 seconds ago, you set uncertaintyInMilliseconds to 60000.

Number

Yes