Alexa Interface Message and Property Reference

When you create an Alexa add-on and implement the Alexa interface in your add-on code, you can send and receive the basic set of Alexa messages. These messages include general Alexa directives and responses, discovery, state reporting, change reporting, and error reporting. Alexa sends directives to your add-on to request something on behalf of the user. If your add-on 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 reference includes the list of Alexa foundational messages and parameters that all add-ons implement.

Message reference

Review the list of messages that Alexa sends to your add-on and the responses and events that your add-on can send to Alexa.

Messages from Alexa to your add-on

The following list includes messages that Alexa sends to your add-on:

AcceptGrant directive – Alexa gives you credentials that identify and authenticate the customer to Alexa.
Discover directive – The customer asks Alexa to connect their device to your smart home add-on.
ReportState directive – Alexa wants to announce or display the state of a device connected to your smart home add-on 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 add-on to Alexa

The following list includes event messages that your add-on 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 add-on.
AddOrUpdateReport event – After the user adds or updates a device connected to your add-on, 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 add-on, you send the event 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 add-on 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 to notify Alexa that your actual response comes later. A limited number of interfaces support a deferred response. For more details, see Deferred response.
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.

You can find examples of all events and responses that you send to Alexa 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": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2.0 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": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2.0 bearer token"
            },
            "endpointId": "Endpoint ID"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2024-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`	Uniquely identifies the message. Include a new value in every response and event that your add-on sends. Amazon recommends using a version 4 UUID. Use for tracking purposes. You can log the message ID, but don’t use the message ID to program business logic. Valid value: String of alphanumeric characters and dashes up to 128 characters.	String	Yes
`correlationToken`	Opaque token that identifies the directive 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`	Version of the interface specified in the namespace field. Valid values: Set to version specified for the interface. For details, see the interface documentation.	String	Yes

Endpoint object

If your add-on controls a physical device or virtual entity, such as a scene or software component, messages to and from Alexa contain an Endpoint object. Messages from your add-on to Alexa include an Endpoint object to help Alexa identify the device and authenticate your add-on. Messages from Alexa contain the same endpointId. 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 endpoint. The ID must be globally unique across all devices and users within the domain of the add-on. You provide the `endpointID` during discovery, and you must use the same ID consistently in all messages that target the same device. Valid value: Up to 256 characters. Can include letters, numbers, spaces, and the following special characters: `_ - = # ; : ? @ &`	String	Yes
`scope`	Bearer token scope to authenticate the add-on. 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 add-on 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 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 token. Valid values: `BearerToken`, `BearerTokenWithPartition`	String	Yes
`token`	OAuth 2.0 bearer token to identify and access a linked customer account. For more details, see OAuth Access Token Types.	String	Yes
`partition`	Location target for the request, such as a room name or number. Valid for `BearerTokenWithPartition` only.	String	No
`userId`	Unique ID 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 add-ons and video skills. The following example shows a BearerToken scope.

    "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
    }

BearerTokenWithPartition scope

The BearerTokenWithPartition scope type provides an OAuth bearer token for accessing a linked user account and specifying a physical location. The following example shows a BearerTokenWithPartition scope.

    "scope": {
        "type": "BearerTokenWithPartition",
        "token": "OAuth2.0 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 event and interface.	`Header` object	Yes
`endpoint`	Identifies the endpoint and provides authorization to authenticate your add-on.	`Endpoint` object	Yes
`payload`	Identifies the properties that changed. If the message doesn’t include a payload, set to an empty object.	Payload object	Yes

Context object

The Context object contains a list of 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 add-on.

    "properties": [{
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2021-11-15T22:00:00.00Z",
            "uncertaintyInMilliseconds": 500
        },
        {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
                "value": "OK"
            },
            "timeOfSample": "2021-11-15T14:20:00.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, not the time that you send the `ChangeReport` event. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ` or `YYYY-MM-DDThh:mm:ss.SSSZ` The timeOfSample can change independently across properties. Update `timeOfSample` for the changed property only.	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

Cause object

The Cause object describes the reason that caused the reported event. Include the Cause object in interfaces that define events.

"cause": {
    "type": "PHYSICAL_INTERACTION"
}

The following table shows the Cause object properties.

Property	Description	Type	Required
`type`	Identifies what caused the change.	`Type` string	Yes

Type values

Use one of the following type values to describe the reason for the event.

Cause type	Description
`APP_INTERACTION`	Customer interaction with a device app. For example, a customer switches on a light or locks a door by using an app provided by the device vendor.
`PERIODIC_POLL`	Periodic poll of an endpoint. For example, you might poll a temperature sensor every hour and send the updated temperature to Alexa.
`PHYSICAL_INTERACTION`	Physical interaction with an endpoint. For example, the user turned on a light or locked a door lock manually.
`VOICE_INTERACTION`	Any user interaction with Alexa. For example, a user turns on a light by speaking to their Echo device, or a user turns off the light by using their Alexa app.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Alexa Interface Message and Property Reference

Message reference

Messages from Alexa to your add-on

Messages from your add-on to Alexa

Message format

Property reference

Header object

Endpoint object

Scope object

BearerToken scope

BearerTokenWithPartition scope

Directive object

Event object

Context object

Payload object

Property object

Cause object

Type values

​Message reference

​Messages from Alexa to your add-on

​Messages from your add-on to Alexa

​Message format

​Property reference

​Header object

​Endpoint object

​Scope object

​BearerToken scope

​BearerTokenWithPartition scope

​Directive object

​Event object

​Context object

​Payload object

​Property object

​Cause object

​Type values

​Related topics

Message reference

Messages from Alexa to your add-on

Messages from your add-on to Alexa

Message format

Property reference

Header object

Endpoint object

Scope object

BearerToken scope

BearerTokenWithPartition scope

Directive object

Event object

Context object

Payload object

Property object

Cause object

Type values

Related topics