Alexa Interface Message and Property Reference
When you create an Alexa skill and implement the Alexa
interface in your skill 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 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 reference includes the list of Alexa
foundational messages and parameters that all skills implement.
Message reference
Review the list of messages that Alexa sends to your skill and the responses and events that your skill can send to Alexa.
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 customer to Alexa.
- Discover directive – The customer 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 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": "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 |
---|---|---|---|
|
Identifies the interface of the message payload. For example, |
String |
Yes |
|
Name of the directive, event, or response in the message. For example |
String |
Yes |
|
Unique identifier for the message. Include a new value in every response and event that your skill sends. Amazon recommends using a version 4 UUID. |
String |
Yes |
|
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 |
String |
No |
|
Version of the interface specified in the namespace field. |
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 |
---|---|---|---|
|
Identifier for the endpoint. The identifier must be unique across all devices owned by the user within the domain of the skill. You provide the |
String |
Yes |
|
Bearer token scope to authenticate the skill. Required for events and asynchronous responses sent to the Alexa gateway. |
Scope object |
No |
|
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. |
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 |
---|---|---|---|
|
Provides the scope type of the token. |
String |
Yes |
|
OAuth 2.0 bearer token to identify and access a linked customer account. |
String |
Yes |
|
Location target for the request, such as a room name or number. |
String |
No |
|
Unique identifier for the user who made the request. Don't rely on this value to identify users. Use |
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.
"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 |
---|---|---|---|
|
Identifies the message and interface. |
|
Yes |
|
Identifies the endpoint that the user wants to control and provides authorization to authenticate Alexa. |
|
Yes |
|
Identifies properties that are part of the directive. |
|
Yes |
Event object
All events and responses to directives include the Event
object.
Property | Description | Type | Required |
---|---|---|---|
|
Identifies the event and interface. |
|
Yes |
|
Identifies the endpoint and provides authorization to authenticate your skill. |
|
Yes |
|
Identifies the properties that changed. |
Payload 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.
payload
or in the context
, but not both.Property | Description | Type | Required |
---|---|---|---|
|
Identifies the retrievable properties of the endpoint. Include one |
Array of |
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-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 |
---|---|---|---|
|
Name of the Alexa capability interface to which the property belongs, such as, |
String |
Yes |
|
Name of the interface instance that you defined in the discovery response. For generic controller interfaces only. For example, |
String |
No |
|
Name of the reported property that belongs to the |
String |
Yes |
|
Value of the reported property. Each Alexa interface defines the type of the |
Various |
Yes |
|
Time the endpoint detected the state change, not the time that you send the Note: When you report state to Alexa, set this value to reflect the time the state change occurred on the device. Don't set the same
timeOfSample value for all properties. For example, for a light that supports Alexa.PowerController and Alex.BrightnessController , if you send a ChangeReport to report the light turned off, update the timeOfSample for the powerState property, but for the brightness property, report the timeOfSample value from the last time the brightness property changed. |
String |
Yes |
|
Uncertainty of the |
Number |
Yes |
Cause object
The Cause
object describes the reason that caused the reported event. The Cause
object is included in interfaces that define events.
"cause": {
"type": "PHYSICAL_INTERACTION"
}
The following table shows the Cause
object properties.
Property | Description | Type | Required |
---|---|---|---|
|
Identifies what caused the change. |
|
Yes |
Type values
Use one of the following type
values to describe the reason for the event.
Cause type | Description |
---|---|
|
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 of an endpoint. For example, you might poll a temperature sensor every hour and send the updated temperature to Alexa. |
|
Physical interaction with an endpoint. For example, the user turned on a light or locked a door lock manually. |
|
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. |
Related topics
Last updated: Sep 04, 2024