Alexa.ReportState and Alexa.StateReport Interfaces 3

Implement the state reporting interfaces in your Alexa add-on 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 add-on 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. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Discovery

During discovery, you identify the interfaces that your add-on supports and the retrievable properties of each interface. When you set retrievable = true for an interface, Alexa can query your add-on for the current state of the properties of that interface.

Discovery response example

The following example shows a Discover.Response message for an Alexa add-on 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": "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 add-on. 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 add-on handles the request successfully, you send the Alexa.StateReport response synchronously from your add-on. 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. To let Alexa know the health of your device, include Alexa.EndpointHealth in your response.

StateReport response example

The following example shows the states of all retrievable properties.

{
    "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-03T08:00:00.10Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2022-02-03T16:20:00.00Z",
                "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 an 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.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Alexa.ReportState and Alexa.StateReport Interfaces 3

Discovery

Discovery response example

Directives

ReportState directive

ReportState directive example

StateReport response

StateReport response example

StateReport response properties

ReportState directive error handling

​Discovery

​Discovery response example

​Directives

​ReportState directive

​ReportState directive example

​StateReport response

​StateReport response example

​StateReport response properties

​ReportState directive error handling

​Related topics

Discovery

Discovery response example

Directives

ReportState directive

ReportState directive example

StateReport response

StateReport response example

StateReport response properties

ReportState directive error handling

Related topics