Understand State and Change Reporting
When you create an Alexa skill that interacts with a smart home device, you can include support for state and change reporting. Alexa notifies users about the state of their devices by voice response or in the Alexa app. For example, in the Alexa app users can see a list of their smart plugs and whether each plug is on or off.
You report state to Alexa in three ways:
- Alexa requests the state with an
Alexa.ReportState
directive. For example, a customer opens the Alexa app to see if the kitchen light is on. You reply with anAlexa.StateReport
that includes a snapshot of all property values. - You proactively send an
Alexa.ChangeReport
event to indicate one or more of the properties that changed. In the event, you also include a snapshot of all other property values. For example, the customer manually turns on the light. In the event, you report the power is on and you also report the brightness of the light. - You proactively send the state of all properties in a directive
Alexa.Response
. For example, when you respond to aTurnOn
directive, you include a snapshot of all property values.
Identify support for state and change reporting
During device discovery, you indicate which Alexa interfaces that you support in your skill. For each interface, you also indicate your support for state and change reporting by using the following properties in your discovery response:
-
Retrievable – The retrievable property controls state reporting. When you set
retrievable = true
for an interface, Alexa can query your skill for the current state of the properties of that interface. Alexa sends anAlexa.ReportState
directive to your skill, and you respond with anAlexa.StateReport
. The default value is false. -
Proactively Reported – The proactively reported property controls change reporting. When you set
proactivelyReported = true
for an interface, your skill sends anAlexa.ChangeReport
event to Alexa when any property of that interface changes. The default value is false. -
Noncontrollable – You can model properties of an endpoint that users can't change by setting
nonControllable
=true
for an interface. For example, when a washing machine automatically goes from wash, to rinse, to spin, you can report the current wash cycle to the user without allowing them to change it. When set to true, Alexa doesn't attempt to change the state. The default value isfalse
.
Discover response example
The following example shows a Discover.Response
message for an oven that supports the Alexa.Cooking
, Alexa.Cooking.TemperatureSensor
, Alexa.Cooking.TemperatureController
, and Alexa.EndpointHealth
interfaces. For more discovery response examples, see the documentation for each interface that you support in your Alexa skill.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [
{
"endpointId": "Unique ID of the endpoint",
"manufacturerName": "Smart Cooking Device Company",
"description": "Brand XYZ oven",
"friendlyName": "Oven",
"displayCategories": ["OVEN"],
"additionalAttributes": {
"manufacturer" : "Smart Cooking Device Company",
"model" : "Sample Model",
"serialNumber": "U11112233456",
"firmwareVersion" : "1.24.2546",
"softwareVersion": "1.036",
"customIdentifier": "Sample custom ID"
},
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.Cooking",
"version": "3",
"properties": {
"supported": [
{
"name": "cookingMode"
},
{
"name": "foodItem"
},
{
"name": "cookingTimeInterval"
}
],
"proactivelyReported": true,
"retrievable": true
},
"configuration": {
"supportedCookingModes": ["REHEAT", "DEFROST", "OFF"]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.Cooking.TemperatureSensor",
"version": "3",
"properties": {
"supported": [
{
"name": "cookingTemperature"
}
],
"proactivelyReported": false,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.Cooking.TemperatureController",
"version": "3",
"properties": {
"supported": [
{
"name": "targetCookingTemperature"
},
{
"name": "preheatTimeInterval"
}
],
"proactivelyReported": true,
"retrievable": true
},
"configuration": {
"supportsRemoteStart": false,
"supportedCookingModes": ["BAKE", "ROAST"]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.2",
"properties": {
"supported": [{
"name": "connectivity"
},
{
"name": "radioDiagnostics"
},
{
"name": "networkThroughput"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Report state in a StateReport
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 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 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.
Specify the following information in the Alexa.StateReport
response:
- Report the state of all the retrievable properties in the
context
object. - Make sure to identify the endpoint for the report in the
endpoint
object. - Set the
payload
to an empty object. - Make sure to include the
correlationToken
set to the value from theAlexa.ReportState
request.
For details about the state report properties, see Alexa.StateReport Interface.
You send the Alexa.StateReport
response synchronously from your skill's Lambda function. Reply within eight seconds.
If you poll your endpoints periodically, you can send cached values for the properties in your response. If the endpoint is unreachable, but you cached all property values, return the Alexa.StateReport
and include all the property values. However, specify the value of the connectivity property of Alexa.EndpointHealth
as UNREACHABLE
. 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
.
ReportState directive example
The following example shows an Alexa.ReportState
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa",
"name": "ReportState",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "endpoint ID",
"cookie": {}
},
"payload": {}
}
}
StateReport response example
The following example shows an Alexa.StateReport
response that your skill sends to Alexa. For more Alexa.StateReport
examples, see the documentation for each interface that you support in your Alexa skill.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint ID",
"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 a ChangeReport
When the state of an endpoint changes for any reason, you report that change to Alexa in an Alexa.ChangeReport
event. Alexa can then provide the 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 interface has changed its value to ON
.
If you specify the properties of an interface as proactivelyReported
during discovery, you must send Alexa an Alexa.ChangeReport
event whenever a 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 details, see Report state in response to a directive.
You send Alexa.ChangeReport
events asynchronously to the Alexa event gateway.
Alexa.ChangeReport
events, request permission to send events to the Alexa event gateway and obtain authentication tokens for each customer. You include the token in the scope
of the event message. For details, see Request Access to the Alexa Event Gateway and Alexa.Authorization
.Specify the following information in the Alexa.ChangeReport
event:
- Include the
cause
object to describe why the property value changed. - Use the
payload
of theAlexa.ChangeReport
to provide the new property value and the reason for the change. You must include at least one property in thepayload
. - Use the
context
of anAlexa.ChangeReport
to report the state of all the other properties of the endpoint that didn't change. List these properties and their values in theproperties
array. - If multiple properties have changed, you can send multiple change report events containing a payload with a single property. Conversely, you can send a single change report event that contains a payload with multiple property values.
- Identify the endpoint for the change report in the
endpoint
object. - Include the access token in the
endpoint.scope
object. - Don't include a
correlationToken
.
For details about the change report properties, see Alexa.ChangeReport Interface.
ChangeReport event example
The following example shows an Alexa.ChangeReport
event for an endpoint that implements the Alexa.PowerController
, Alexa.BrightnessController
, and Alexa.EndpointHealth
interfaces. The event reports that the endpoint changed its brightness
value to 85 percent due to a physical interaction with the device. The event specifies the new brightness
value in the payload
, and it specifies the Alexa.PowerController
and Alexa.EndpointHealth
properties in the context
object because these values didn't change. For more Alexa.ChangeReport
examples, see the documentation for each interface that you support in your Alexa skill.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "endpoint ID",
"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
},
{
"namespace": "Alexa.EndpointHealth",
"name": "battery",
"value": {
"health": {
"state": "WARNING",
"reasons": ["LOW_CHARGE"]
},
"levelPercentage": 45
},
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Report state in a directive response
If Alexa sends a directive to change the state of a property, and you handle the directive successfully, send an Alexa.Response
. 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
object.
Specify the following information in the Alexa.Response
:
- Report the state of all the retrievable properties in the
context
object, including the changed properties.Note: Amazon recommends that you specify the state of all the properties of the endpoint, including the properties that didn't change. - Identify the endpoint for the response in the
endpoint
object. - Include the
correlationToken
set to the value from the directive request. - If you send the response asynchronously, you must include the access token in the endpoint
endpoint.scope
object.
You can send response events synchronously from your skill's Lambda function or asynchronously to the Alexa event gateway. For details about response properties, see Response Events.
Directive example
The following example shows a directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.PercentageController",
"name": "AdjustPercentage",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "endpoint ID",
"cookie": {}
},
"payload": {
"percentageDelta": -20
}
}
}
Directive response example with state
The following example shows an asynchronous response that your skill sends to Alexa. The example includes the state properties in the context
object.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "endpoint ID"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 75,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Directive response example for a property that isn't retrievable
After your skill successfully handles a directive for an endpoint with properties that aren't retrievable, the skill must send a response that doesn't include the properties in the context
.
The following example shows synchronous Alexa.Response
event that indicates to Alexa that you handled the TurnOn
directive successfully. The empty properties
array in the event context
indicates that you can't determine the property state after the change.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint ID"
},
"payload": {}
},
"context": {
"properties": []
}
}
Sample code
The following sample code demonstrates how to set up your smart home skill to send change reports to the Alexa event gateway:
Related topics
Last updated: Nov 22, 2023