Alexa.ReportState and Alexa.StateReport Interfaces
Implement the state reporting interfaces in your skill so that users can ask Alexa for the state of their device. For example, a customer might check the Alexa app for the status of a light on a different floor of their house. Alexa sends an Alexa.ReportState
directive to query your skill for the current state of all retrievable properties of an interface. You respond with an Alexa.StateReport
. In this example, the Alexa.ReportState
directive includes the endpoint ID of the light.
For details about state reporting, see Understand State and Change Reporting.
Discovery
During discovery, you identify the interfaces that your skill supports and the retrievable properties of each interface. When you set retrievable = true
for an interface, Alexa can query your skill for the current state of the properties of that interface.
Discover response example
The following example shows a Discover.Response
message for an Alexa skill that controls a light and supports the Alexa.PowerController
, Alexa.BrightnessController
, and Alexa.EndpointHealth
interfaces. The powerState
, brightness
, and connectivity
properties are retrievable.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "a unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "unique ID of the endpoint of the light",
"manufacturerName": "the manufacturer name of the endpoint",
"description": "a description that is shown in the Alexa app",
"friendlyName": "Living Room Light",
"displayCategories": ["LIGHT"],
"additionalAttributes": {
"manufacturer": "the manufacturer name of the endpoint",
"model": "the model of the device",
"serialNumber": "the serial number of the device",
"firmwareVersion": "the firmware version of the device",
"softwareVersion": "the software version of the device",
"customIdentifier": "your custom identifier for the device"
},
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [{
"name": "powerState"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.BrightnessController",
"version": "3",
"properties": {
"supported": [{
"name": "brightness"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
Directives
ReportState directive
When Alexa sends an Alexa.ReportState
directive to request the state of an endpoint, you send an Alexa.StateReport
response. This response contains the current state of all the properties that are retrievable for the endpoint.
ReportState directive example
The following example shows an Alexa.ReportState
directive that Alexa sends to your skill. The endpointId
identifies the device.
{
"directive": {
"header": {
"namespace": "Alexa",
"name": "ReportState",
"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 of the light",
"cookie": {}
},
"payload": {}
}
}
StateReport response
If your skill handles the request successfully, you send the Alexa.StateReport
response synchronously from your skill. Include the correlationToken
set to the value from the Alexa.ReportState
request.
StateReport response example
The following example shows the states of all retrievable properties.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"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 of the light"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "OFF",
"timeOfSample": "2022-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 75,
"timeOfSample": "2022-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2022-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
StateReport response properties
Property | Description | Type | Required |
---|---|---|---|
|
Identifies the endpoint for the report. |
|
Yes |
|
Report the state of all the retrievable properties. |
|
Yes |
ReportState directive error handling
If you can't handle a Alexa.ReportState
directive successfully, respond with an Alexa.ErrorResponse
event. If you can't report the state of all the properties because the endpoint is unreachable and you haven't cached the values, send an Alexa.ErrorResponse
of type BRIDGE_UNREACHABLE
or ENDPOINT_UNREACHABLE
.