Understand State and Change Reporting
When you develop a smart home skill, you can include support for state and change reporting for device endpoints. Alexa notifies users about the state of endpoints either by voice or in the Alexa app.
During device discovery, you must identify what state reporting you support for each property of your device. After device discovery, Alexa can request the state of your device properties, and you send the information back to Alexa in response events. Alexa requests endpoint state by sending you a control directive or a report state directive.
You can also proactively report state to Alexa as a change report event.
- Identify support for state and change reporting during discovery
- Report state in an Alexa.StateReport
- Report state in an Alexa.ChangeReport
- Report state in an Alexa.Response
- Property object
- Related Topics
Identify support for state and change reporting during discovery
To enable state reporting, you must indicate during device discovery whether each property of an endpoint is retrievable or proactivelyReported.
When you set retrievable=true for a property, it means that Alexa can query the property for its current state. To query for the state, Alexa sends a ReportState directive, and you respond with a StateReport event. If you don't specify retrievable, the default value is false.
When your set proactivelyReported=true for a property, it means that you send a ChangeReport event for the endpoint when the state of the property changes for any reason. If you don't specify proactivelyReported, the default value is false.
When new properties and directives are added to an interface, Alexa only uses them with an endpoint if the endpoint specified them as supported during discovery. For more information about device discovery, see Alexa.Discovery.
For each property, there are four combinations of retrievable and proactivelyReported:
| Property Values | Description |
|---|---|
"proactivelyReported": true
"retrievable": true
|
For a property with these values, your skill sends ChangeReport events and the property can be queried. For example, a light bulb that can be queried for state and also sends ChangeReport events when the state changes because of a physical interaction with the device.
|
"proactivelyReported": false
"retrievable": true
|
For a property with these values, your skill does not send ChangeReport events, but can be queried because it responds to ReportState directives. For example, a light bulb that can be queried for state but does not send ChangeReport events when physical interactions occur.
|
"proactivelyReported": true
"retrievable": false
|
For a property with these values, your skill sends ChangeReport events, but the property cannot be queried. For example, a low energy device that is normally in a dormant state cannot be queried. However, the device activates when a setting changes and sends a ChangeReport event.
|
"proactivelyReported": false
"retrievable": false
|
For a property with these values, your skill does not send ChangeReport events and the property cannot be queried. For example, a device that is controlled by an infrared transmitter. Infrared is a one-way control mechanism. Commands can be sent to the device, but it does not support a mechanism for sending messages about its state and its state cannot be queried.
|
Example discovery response with properties defined
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "abc-123-def-456"
},
"payload": {
"endpoints": [
{
"endpointId": "uniqueIdOfLight",
"friendlyName": "Living Room Light",
"description": "a description that is shown to the customer",
"displayCategories": [
"THERMOSTAT"
],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
},
{
"type": "AlexaInterface",
"interface": "Alexa.ColorTemperatureController",
"version": "3",
"properties": {
"supported": [
{
"name": "colorTemperatureInKelvin"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3",
"properties": {
"supported": [
{
"name": "connectivity"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": true,
"retrievable": true
}
}
]
}
]
}
}
}
Report state in an Alexa.StateReport
When Alexa sends a ReportState directive to request the state of an endpoint, you send a StateReport event in response. This response contains the current state of all of the properties that are retrievable in the context object.
For example, a customer might check the Alexa app for the status of a light on a different floor of their house. Alexa sends a ReportState directive for the light. You send a response that includes the state of all the retrievable properties for the light, and the app reports the state to the customer.
If you poll your endpoints periodically, you can send cached values for the properties in your response. If the endpoint is currently unreachable, but all property values are cached, then return the StateReport and include all of the property values. However, specify the value of the connectivity property of EndpointHealth as UNREACHABLE. If you can't report the state of all the properties because the endpoint is unreachable and you have not cached the values, send an ErrorResponse of type BRIDGE_UNREACHABLE or ENDPOINT_UNREACHABLE.
You can send a StateReport synchronously from your skill's Lambda function or asynchronously to the event gateway.
Example ReportState directive
{
"directive": {
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "abcdef-123456",
"namespace": "Alexa",
"name": "ReportState",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "appliance-001",
"cookie": {},
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
}
},
"payload": {}
}
}
Example StateReport response event
{
"event": {
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "abcdef-123456",
"namespace": "Alexa",
"name": "StateReport",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "appliance-001",
"cookie": {}
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 25.0,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 6000
},
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "HEAT",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 6000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Report state in an Alexa.ChangeReport
When the state of an endpoint changes for any reason, you report that change to Alexa in a ChangeReport event. Alexa can then provide that status change to the customer. In the change report, specify the state of any changed properties in the payload object. For example, if a customer manually turns on a light, send a change report event that indicates the powerState property of the [Alexa.PowerController][alexa-powercontroller] interface has changed its value to ON.
If a property is specified as proactivelyReported during discovery, you must send Alexa a ChangeReport event whenever that property value changes.
If a state change happens because of a directive from Alexa, you send both a directive response and a change report event. For more information, see Report state in response to a control directive.
ChangeReport events, you must request permission to send events to the event gateway and obtain authentication tokens for each customer, which you include in the scope of the event message. For more information, see Authenticate a Customer to Alexa with Permissions and Alexa.Authorization.- Use the
payloadof theChangeReportto provide the new property value and the reason for the change. - You use the
contextof aChangeReportto report the state of any additional properties. - If multiple properties have changed, you can send Alexa multiple change report events containing a payload with a single property, or a single change report event that contains a payload with multiple property values.
- Make sure to identify the customer and the endpoint for the change report in the
endpointobject.
In the context object, specify the state of all the other properties of the endpoint that didn't change, to help improve the customer experience.
payload or the context, but not both.Example ChangeReport event
The following example shows a ChangeReport event for an endpoint that implements the Alexa.PowerController and Alexa.BrightnessController interfaces. The event reports that the endpoint changed its brightness value to 85% due to a physical interaction with the device. The event specifies the new brightness value in the payload, and it specifies the powerState property in the context object because the value did not change.
{
"event": {
"header": {
"messageId": "abc-123-def-456",
"namespace": "Alexa",
"name": "ChangeReport",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "endpoint-001",
"cookie": {
"path": "path/for/this/endpoint"
}
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 85,
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"context": {
"properties": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 60000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Payload details
The payload of a ChangeReport event specifies a change object that contains an array of changed properties and a cause object that specifies a reason for the change. For more information, see property object and cause object.
Cause Object
The cause attribute is used to describe the cause of a property value change when you send a ChangeReport event.
| Cause Type | Description |
|---|---|
APP_INTERACTION |
Indicates that the event was caused by a customer interaction with an application. For example, a customer switches on a light or locks a door using the Alexa app or an app provided by a device vendor. |
PHYSICAL_INTERACTION |
Indicates that the event was caused by a physical interaction with an endpoint. For example, manually switching on a light or manually locking a door lock. |
PERIODIC_POLL |
Indicates that the event was caused by the periodic poll of an endpoint, which found a change in value. For example, you might poll a temperature sensor every hour and send the updated temperature to Alexa. |
RULE_TRIGGER |
Indicates that the event was caused by the application of a device rule. For example, a customer configures a rule to switch on a light if a motion sensor detects motion. In this case, Alexa receives an event from the motion sensor, and another event from the light to indicate that its state change was caused by the rule. |
VOICE_INTERACTION |
Indicates that the event was caused by a voice interaction. For example, a user speaking to their Echo device. |
Report state in an Alexa.Response
If Alexa sends a directive to change the state of a property, and you handle the directive successfully, send a response event. In the response, specify the state of any changed properties in the context object. For example, if Alexa sends an Alexa.PowerController.TurnOn directive, you send a response event that includes the powerState property, with its new value ON, in the context.
We recommend that you specify the state of all the properties of the endpoint, including the properties that didn't change, to help improve the customer experience.
You can send response events synchronously from your skill's Lambda function or asynchronously to the event gateway.
Example control directive
{
"directive": {
"header": {
"namespace": "Alexa.PowerController",
"name": "TurnOn",
"payloadVersion": "3",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "appliance-001"
},
"payload": {}
}
}
Example response containing property state
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"payloadVersion": "3",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "appliance-001"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 85,
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Example response for a property that is not retrievable
After your skill successfully handles a directive for an endpoint with properties that are not retrievable, the skill must send a response event that does not include the properties in the context.
The following example shows a Response event that indicates to Alexa that the TurnOn directive was handled successfully. The empty properties array in the event context indicates that the property state after the change cannot be determined.
{
"event": {
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "abcdef-123456",
"namespace": "Alexa.PowerController",
"name": "Response",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "endpoint-id"
},
"payload": {}
},
"context": {
"properties": []
},
}
Property object
The property object communicates information about each property of an endpoint. You describe the properties that are supported for an endpoint during discovery, and then send properties and their state information in events.
| Field | Description |
|---|---|
namespace |
The namespace of the property. |
name |
The name of the property. |
value |
The current value of the property. |
timeOfSample |
The time at which the property value was recorded. Specify the time as a string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. |
uncertaintyInMilliseconds |
The number of milliseconds that have elapsed since the property value was last confirmed. For example, if you last obtained this value 60 seconds ago, the uncertainty time is 60000. |
