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.

Copied to clipboard.

{
    "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.

Copied to clipboard.

{
    "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

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.