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 a ReportState directive. For example, a customer opens the Alexa app to see if the kitchen light is on. You reply with a StateReport that includes a snapshot of all property values.
  • You proactively send a 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 Response. For example, when you respond to a TurnOn 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 a ReportState directive to your skill, and you respond with a 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 a 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 will not attempt to change the state. The default value is false.

Discover response example

The following example shows a Discover.Response message for an oven supports the Alexa.Cooking, Alexa.Cooking.TemperatureSensor, Alexa.Cooking.TemperatureController, and EndpointHealth interfaces. For more example discovery code, see the documentation for each interface that you support in your Alexa skill.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "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",
                "properties": {
                    "supported": [{
                            "name": "connectivity"
                        },
                        {
                            "name": "battery"
                        },
                        {
                            "name": "radioDiagnostics"
                        },
                        {
                            "name": "networkThroughput"
                        }
                    ],
                    "proactivelyReported": true,
                    "retrievable": true
                }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Report state in a StateReport

When Alexa sends a ReportState directive to request the state of an endpoint, you send a 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 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.

Specify the following information in the StateReport:

  • 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.
  • Make sure to include the correlationToken set to the value from the ReportState request.

You can send response events synchronously from your skill's Lambda function.

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 StateReport and include all 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 haven't cached the values, send an ErrorResponse of type BRIDGE_UNREACHABLE or ENDPOINT_UNREACHABLE.

ReportState directive example

The following example shows a ReportState directive that Alexa sends to your skill.

ReportState directive example

{
  "directive": {
    "header": {
      "namespace": "Alexa",
      "name": "ReportState",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {}
  }
}

StateReport response example

The following example shows a StateReport response that your skill sends to Alexa. For more StateReport examples, see the documentation for each interface that you support in your Alexa skill.

StateReport response example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token that matches the request>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "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
      }
    ]
  }
}

StateReport message details

Property Description Type

event

Defines header and endpoint information.

An Event object

context

Includes the state of all the retrievable properties.

A Context object

Report state in a 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 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 a property 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 details, see Report state in response to a directive.

Specify the following information in the ChangeReport event:

  • Include the cause object to describe why the property value changed.
  • Use the payload of the ChangeReport to provide the new property value and the reason for the change. You must include at least one property in the properties array.
  • You use the context of a ChangeReport to report the state of all the other properties of the endpoint that didn't change. List these properties and their values in the properties array.
  • If multiple properties have changed, you can send 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 that you identify the customer and the endpoint for the change report in the endpoint object.
  • Don't include a correlationToken.

ChangeReport event example

The following example shows a ChangeReport event for an endpoint that implements the Alexa.PowerController, Alexa.BrightnessController, and EndpointHealth 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 Alexa.PowerController and EndpointHealth properties in the context object because these values didn't change. For more example ChangeReport code, see the documentation for each interface that you support in your Alexa skill.

ChangeReport event example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "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": "2021-11-15T14:20:00Z",
        "uncertaintyInMilliseconds": 60000
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2021-11-15T14:20:00Z",
        "uncertaintyInMilliseconds": 0
    },
    {
        "namespace": "Alexa.EndpointHealth",
        "name": "battery",
        "value": {
            "health": {
                "state": "WARNING",
                "reasons": ["LOW_CHARGE"]
            },
            "levelPercentage": 45
        },
        "timeOfSample": "2021-11-15T14:20:00Z",
        "uncertaintyInMilliseconds": 0
    }
    ]
  }
}

ChangeReport message details

Property Description Type

event

Defines the header and endpoint information and the reportable properties.

An Event object

context

Includes the state of all the retrievable properties.

A Context object

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 a 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 directive Response:

  • Report the state of all the retrievable properties in the context object, including the changed properties.
  • Make sure to identify the endpoint for the report in the endpoint object. Make sure to include the correlationToken set to the value from the directive request.

Amazon recommends that you specify the state of all the properties of the endpoint, including the properties that didn't change.

You can send response events synchronously from your skill's Lambda function or asynchronously to the event gateway.

Example directive

The following example shows a directive that Alexa sends to your skill.

Example directive

{
  "directive": {
    "header": {
      "namespace": "Alexa.PercentageController",
      "name": "AdjustPercentage",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {
      "percentageDelta": -20
    }
  }
}

Directive response example with property state

The following example shows a response that your skill sends to Alexa.

Directive response example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 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 a 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.

Directive response example

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "<message id>",
            "correlationToken": "<an opaque correlation token>",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "<an OAuth2 bearer token>"
            },
            "endpointId": "<endpoint id>"
        },
        "payload": {}
    },
    "context": {
        "properties": []
    }
}

Directive response details

Property Description Type

event

Defines header and endpoint information.

An Event object

context

Includes the state of all the retrievable properties.

A Context object

Properties and objects

The state reporting interfaces use the following properties and objects.

Event object

All responses to Alexa include the Event object.

Event object details

Property Description Type

header

The message header. This field includes the event name, payload version, message ID, and correlation token.

A Header object

endpoint

Identifies the endpoint and provides authorization to authenticate your skill.

An Endpoint object

payload

The endpoint property that changed and the reason for change.
For StateReport and Response events, set to an empty object.

A Payload object

Context object

The Context object contains a list all reportable properties of the endpoint. To include a property, you must define the property as retrievable = true in your discovery response.

Context object details

Property Description Type

properties

Identifies the retrievable properties of the endpoint. Include one Property object for each property reported.

An array of Property objects

Payload object

The Payload object includes the reason that the skill reports a change and the list of changed property values. To include a property, you must define the property as proactivelyReported = true in your discovery response. You include only property values that changed in the Payload object.

Payload object details

Property Description Type

change

The reason for the change and list of changed properties.

A Change object

Change object

Include the Change object to report the changed properties and the reason for the change.

Change object details

Property Description Type

cause

The reason for the change in one or more properties.

A Cause object

properties

Identifies the list of reportable properties that changed. Include one Property object for each property change reported.

An array of Property objects

Property object

The Property object defines a reportable property of the endpoint. Each Alexa interface defines the property name and value. For details, see the documentation for each interface that you support in your Alexa skill.

Property object details

Property Description Type

namespace

The name of the Alexa capability interface to which the property belongs, such as, Alexa.PowerController.

String

instance

(Optional) For generic controller interfaces, the instance of the interface. For example, Dryer.Temperature.

String

name

The name of the reported property that belongs to the namespace.

String

value

The value of the reported property. Each Alexa interface defines the type of the value field.
For details, see the documentation for each interface that your skill uses.

Various

timeOfSample

The time the endpoint detected the state change.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

uncertaintyInMilliseconds

The uncertainty of the timeOfSample field in milliseconds.
This field represents the number of milliseconds after the endpoint last confirmed the property value. For example, if the endpoint sampled the property value 60 seconds ago, you set uncertaintyInMilliseconds to 60000.

Number

Property object example

    "properties": [{
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2021-11-15T14:20:00Z",
            "uncertaintyInMilliseconds": 0
        },
        {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
                "value": "OK"
            },
            "timeOfSample": "2021-11-15T14:20:00Z",
            "uncertaintyInMilliseconds": 0
        }
    ]

Cause object

When you send a ChangeReport event, use the Cause object to describe the cause of property value change.

Cause object details

Property Description Type

type

Identifies the reason for the change.

A Type String

Cause object example

    "cause": {
          "type": "APP_INTERACTION"
    }

Type values

The following table describes the type values.

Cause Type Description
APP_INTERACTION Customer interaction with an app. For example, a customer switches on a light or locks a door by using the Alexa app or an app provided by a device vendor.
PERIODIC_POLL Periodic poll of an endpoint. For example, you might poll a temperature sensor every hour and send the updated temperature to Alexa.
PHYSICAL_INTERACTION Physical interaction with an endpoint. For example, the user turned on a light or locked a door lock manually.
RULE_TRIGGER A device rule. For example, a user 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 Voice interaction. For example, a user turns on a light by speaking to their Echo device.