Alexa.ReportState and Alexa.StateReport Interfaces 3

Note: Sign in to the developer console to build or publish your skill.

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.

Important: To provide the best experience for the user, Amazon recommends that you send state reports from your skill for most devices and interfaces. Exceptions include low-energy devices that are normally in a dormant state, infrared transmitters, and others.

For the definitions of the message properties, see Alexa Interface Message and Property Reference.

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.

Discovery 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.

Copied to clipboard.

{
    "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 of the light",
                "manufacturerName": "Manufacturer of the endpoint",
                "description": "Description to be shown in the Alexa app",
                "friendlyName": "Living Room Light",
                "displayCategories": ["LIGHT"],
                "additionalAttributes": {
                    "manufacturer": "Manufacturer of the endpoint",
                    "model": "Model of the device",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional 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": "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 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. Report the state of all the retrievable properties in the context object and set the payload to an empty object.

Important: If you send a DeferredResponse event in response to Alexa.ReportState, you must follow it with the Alexa.StateReport response within 8 seconds.

StateReport response example

The following example shows the states of all retrievable properties.

Copied to clipboard.

{
    "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 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
`event`	Identifies the endpoint for the report. Include an empty `payload` object.	`Event` object	Yes
`context`	Report the state of all the retrievable properties.	`Context` object	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.

Last updated: Oct 19, 2022