Understand State and Change Reporting

When you create an Alexa skill that interacts with a smart home device, you include support for state and change reporting. Alexa notifies users about the state of their devices by voice response, in the Alexa app, and on Alexa-enabled devices with a screen. For example, in the Alexa app users can see a list of their smart plugs and whether each plug is on or off. On the Amazon Echo Hub, users can see a quick view about the status of their Alexa-connected smart devices. The visibility of device state makes reliable and accurate state reporting essential to the user experience.

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 an Alexa.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 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 include the set of properties that are applicable to your device. For these reportable properties, you indicate support for state and change reporting by using the following parameters 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 reportable properties of that interface. Alexa sends an Alexa.ReportState directive to your skill, and you respond with an Alexa.StateReport and include the state of all reportable properties for each interface. If you set retrievable to false, Alexa can't accurately display or respond when the customer asks for the state of their device.

• Proactively Reported – The proactively reported property controls change reporting. When you set proactivelyReported = true for an interface, you send an Alexa.ChangeReport event to Alexa when any reportable property of that interface changes, such as a manual change. You include the state of unchanged properties in the Alexa.ChangeReport, too. If a state change happens because of a directive from Alexa, you send both a directive response and a change report event. If you set proactivelyReported to false, Alexa can't display the current state of the device on the Alexa app or on Alexa-enabled devices with a screen, such as the Amazon Echo Hub.

• Noncontrollable – To model properties of an endpoint that users can't change, set 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 is false.

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. Each interface includes the properties that are retrievable and proactively reported. 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.1",
                "properties": {
                    "supported": [{
                            "name": "connectivity"
                        }
                    ],
                    "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 the Alexa.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": "2023-07-03T10:20:50.52Z",
        "uncertaintyInMilliseconds": 6000
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2023-07-03T10:20:50.52Z",
        "uncertaintyInMilliseconds": 6000
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2023-07-05T12:00:00.02Z",
        "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. Alexa expects a ChangeReport within three seconds of a device state change. For details, see Report state in response to a directive.

You send Alexa.ChangeReport events asynchronously to the Alexa event gateway.

Specify the following information in the Alexa.ChangeReport event:

• Include the cause object to describe why the property value changed.
• Use the payload of the Alexa.ChangeReport to provide the new property value and the reason for the change. You must include at least one property in the payload.
  • Include the timeOfSample to reflect the time the property state changed on the endpoint, not the time that you send the Alexa.ChangeReport event.
• Use the context of an Alexa.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.
  • Here, you report the timeOfSample for each property from the last reported change for that property.
• If multiple properties have changed, you can send multiple change report events containing a payload with a single property. Or, 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": "2023-07-05T12:08:00.02Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2023-07-03T10:20:50.52Z",
        "uncertaintyInMilliseconds": 60000
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2023-07-05T12:00:00.02Z",
        "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 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": "2023-07-01T12:01:00.02Z",
        "uncertaintyInMilliseconds": 1000
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
            "value": "OK"
        },
        "timeOfSample": "2023-07-05T12:00:00.02Z",
        "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": []
    }
}

Best practices for state reporting

To make sure that Alexa and the device app reflect the same and accurate device state to customers, follow these best practices for state reporting. For more details about the reporting flow, see State reporting examples.

• In your discovery response, mark each reportable property as retrievable = true and proactivelyReported = true for each of the interfaces that your skill supports.
• Always report the state of all capability properties in the context of an Alexa.Response event when you respond to a control directive, including the Alexa.EndpointHealth.connectivity property.
• Proactively report the state of your device to Alexa by sending Alexa.ChangeReport events when the state of any reportable property changes for any reason, including a state change that happens because of a directive from Alexa.
  • Update timeOfSample for the changed property only. For other properties, report the timeOfSample that reflects the last time the property changed. Don't set the same timeOfSample value for all properties.
• Send the Alexa.ChangeReport with the new property value within three seconds of the state change. The Alexa.ChangeReport must also include the current value of the connectivity property.
• If a Alexa.ChangeReport event fails with HTTP errors 503, 429, or 401, or the message times out, resend the Alexa.ChangeReport at least two more times with a delay of no more than 15-second intervals between each try.
• Make sure that you use the same data type and scale when you report state. For example, if you report integer in StateReport, don't report float in Alexa.ChangeReport. Or, if you report Fahrenheit in Alexa.Response, don't report Celsius in Alexa.ChangeReport. These mistakes cause Alexa to send more ReportState messages, increasing traffic to your skill.
• A race condition can occur between an Alexa.StateReport response from your skill and an Alexa.ChangeReport from your device cloud. To make sure that Alexa shows the correct state of every property, update the timeOfSample value only when the property value changes on the device. For example, for a new light that changes color, report the timeOfSample as follows:
  • At 8:00 AM, the user turns on the light. Report powerState=ON, timeOfSample=2024-09-05T08:00:00Z.
  • At 12:00 PM, the user asks Alexa to set the light to blue. Report color(HSB)=Blue, timeOfSample=2024-09-05T12:00:00Z and powerState=ON, timeOfSample=2024-09-05T08:00:00Z.
  • At 8:00 PM, the user turns off the light. Report powerState=OFF, timeOfSample=2024-09-05T20:00:00Z and color(HSB)=Blue, timeOfSample=2024-09-05T12:00:00Z.
  • At 9:00 PM, the user turns on the light. Report powerState=ON, timeOfSample=2024-09-05T21:00:00Z and color(HSB)= Blue, timeOfSample=2024-09-05T12:00:00Z.

State reporting examples

The following examples show state reporting for specific device types. However, these examples apply to most device types.

Smart lock example

The following examples show customer interaction with a smart lock. The capabilities reported for the device are lock state and endpoint health.

Color light bulb example

The following examples show customer interaction with a color light bulb. The capabilities reported for the device are power, color, brightness, color temperature, and endpoint health.

Sample code

The following sample code demonstrates how to set up your smart home skill to send change reports to the Alexa event gateway:

• Smart Home Skill Sample: Send Change Report (Python)

Related topics

• About Alexa Discovery
• State and change reporting requirements for WWA
• View Operational Metrics for Smart Home and Video Skills
• List of Alexa Interfaces

Last updated: Sep 04, 2024