Understand State Reporting for a Smart Home Skill

When you implement your smart home skill, you have the ability to update Alexa on the state of endpoints. Alexa uses this information to keep the customer up-to-date either by voice or in the Alexa app.

Ways to report state

You use the Alexa Skills Kit smart home capability interfaces to describe a smart home device (endpoint) and its properties. You report the state of these properties in the following ways:

In response to a directive

There are two ways to report property state in response to a directive:

In response to a control directive

When you send a Response event to indicate that the request completed successfully, you also report the state of any changed properties in the context object of the response. You can include additional properties that you think might have changed.

For example, when responding to a TurnOn directive, you send a Response event that includes the the powerState property. You can optionally include the state of all the endpoint's properties, which can improve the customer experience. You can send response events synchronously from your skill's Lambda function or asynchronously to the event gateway.

In response to a ReportState directive

Alexa sends a ReportState directive requesting an endpoint's state, and you send a StateReport event in response. This response contains the current state of all of the properties that are retrievable.

For example, a customer might check the Alexa app, which prompts Alexa to query the state of one of your endpoints. You send a response that includes the state of all the retrievable properties for that endpoint. You can send a StateReport synchronously from your skill's Lambda function or asynchronously to the event gateway.

For more information, see report state when Alexa requests it.

As a change report

When the state of an endpoint changes for any reason, you report that change to Alexa in a ChangeReport event. Alexa can then provide that status change to the customer.

For example, when a light is switched on, you send a change report to Alexa indicating that the powerState property value has changed to ON. If the change happened because of a directive from Alexa, you send both a Response and a ChangeReport event. In addition, you can report the state of other (non-changed) properties in the context object. This is optional, but recommended.

For more information, see report state with ChangeReport events.

Indicate state reporting support during discovery

To enable state reporting, you must indicate during discovery whether each property of an endpoint is retrievable and proactivelyReported.

  • When a property's retrievable value is true, it means that the property can be queried for its current state. To query for the state, Alexa sends a ReportState directive and your skill responds with a StateReport.
  • When a property's proactivelyReported value is true, it means that you send ChangeReport events for an endpoint when the state of the endpoint changes for any reason.

There are four combinations of these values for each property:

Property Values Description
"proactivelyReported": true "retrievable": true For a property with these values, your skill sends ChangeReport events and the property can be queried. For example, a light bulb that can be queried for state and also sends ChangeReport events when the state changes because of a physical interaction with the device.
"proactivelyReported": false "retrievable": true For a property with these values, your skill does not send ChangeReport events, but can be queried because it responds to ReportState directives. For example, a light bulb that can be queried for state but does not send ChangeReport events when physical interactions occur.
"proactivelyReported": true "retrievable": false For a property with these values, your skill sends ChangeReport events, but the property cannot be queried. For example, a low energy device that is normally in a dormant state cannot be queried. However, the device activates when a setting changes and sends a ChangeReport event.
"proactivelyReported": false "retrievable": false For a property with these values, your skill does not send ChangeReport events and the property cannot be queried. For example, a device that is controlled by an infrared transmitter. Infrared is a one-way control mechanism. Commands can be sent to the device, but it does not support a mechanism for sending messages about its state and its state cannot be queried.

Example discovery message with properties defined

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "uniqueIdOfLight",
          "friendlyName": "Living Room Light",
          "description": "a description that is shown to the customer",
          "displayCategories": [
            "THERMOSTAT"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ColorTemperatureController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "colorTemperatureInKelvin"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            }
          ]
        }
      ]
    }
  }
}

Note that:

  • If you do not specify values for retrievable or proactivelyReported for a property, then by default Alexa considers those values false.
  • If the properties object is missing entirely, then by default Alexa considers the values for retrievable and proactivelyReported to be false.
  • When new properties and directives are added to an interface, Alexa only uses them with an endpoint if the endpoint specified them as supported during discovery.

For more information, see Alexa.Discovery.

Report state with a context object in response events

Use the required context object to report the state of properties in any event message. A context contains an array of property objects and their current state, which might or might not have changed. For information about which properties support state reporting, see Property Schemas.

You can send state information in a context when you receive a directive that results in a state change. For example, Alexa sends a TurnOn directive.

{
  "directive": {
    "header": {
      "namespace": "Alexa.PowerController",
      "name": "TurnOn",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

You apply the TurnOn directive to the endpoint and then respond with a Response event that includes a context object that contains all of the property values for the endpoint.

When you send a response event with context, you should report the state of all properties of the endpoint and make sure that the values reported account for all of the side effects from handling the directive.

The following example shows the context of a Response event for an endpoint property that implements the Alexa.PowerController and Alexa.BrightnessController interfaces. The event includes the same correlationToken in the message header that was present in the directive.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.BrightnessController",
        "name": "brightness",
        "value": 85,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

Property object

The property object communicates which property has changed, its new value, and when it changed. You describe the properties that are supported for an endpoint during discovery, and then send properties that contain state information in events. For Response events, send all properties that contain state information in the context.

Field Description
namespace The namespace of the property that changed.
name The name of the property that changed.
value The new value for the property.
timeOfSample The time at which the property value changed. Specify the time in ISO 8601 format in UTC. For example: 2018-10-09T19:36:13+00:00
uncertaintyInMilliseconds The number of milliseconds that have elapsed since the property was last confirmed. For example, if you last obtained this value 60 seconds ago, the uncertainty time is 60000.

Example response for a powerState property that is not retrievable

After your skill successfully handles a directive for an endpoint with properties that are not retrievable, the skill must send a Response event that does not include the properties in the context.

The following example shows a Response event that indicates to Alexa that the TurnOn directive was handled successfully. The empty properties array in the event context indicates that the property state after the change cannot be determined.

{
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "namespace": "Alexa.PowerController",
      "name": "Response",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "endpoint-id"
    },
    "context": {
      "properties": []
    },
    "payload": {}
  }
}

Report state when Alexa requests it

To request a state report, Alexa sends a ReportState directive that specifies the endpoint. See the following example. When you receive a message like this, you report state on all of the properties that you defined during the discovery process as being retrievable.

Example ReportState directive

{
  "directive": {
    "header": {
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "namespace": "Alexa",
      "name": "ReportState",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "appliance-001",
      "cookie": {},
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      }
    },
    "payload": {}
  }
}

In response you send a StateReport, which must include a context object that contains all of the relevant reportable properties of each capability interface and their current values. You may send the cached values for the properties if you poll your endpoints periodically.

If the endpoint is currently unreachable but you can report all endpoint property values because they are cached, then return the StateReport and include all of the property values. However, specify the value of the connectivity property of EndpointHealth as UNREACHABLE. If you cannot report the state of all the properties because the endpoint is unreachable and you have not cached the values, you should send an ErrorResponse of type BRIDGE_UNREACHABLE or ENDPOINT_UNREACHABLE.

Example StateReport event

{
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "namespace": "Alexa",
      "name": "StateReport",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "context": {
      "properties": [
        {
          "namespace": "Alexa.ThermostatController",
          "name": "targetSetpoint",
          "value": {
            "value": 25.0,
            "scale": "CELSIUS"
          },
          "timeOfSample": "2017-02-03T16:20:50.52Z",
          "uncertaintyInMilliseconds": 6000
        },
        {
          "namespace": "Alexa.ThermostatController",
          "name": "thermostatMode",
          "value": "HEAT",
          "timeOfSample": "2017-02-03T16:20:50.52Z",
          "uncertaintyInMilliseconds": 6000
        },
        {
          "namespace": "Alexa.EndpointHealth",
          "name": "connectivity",
          "value": {
            "value": "OK"
          },
          "timeOfSample": "2017-02-03T16:20:50.52Z",
          "uncertaintyInMilliseconds": 0
        }
      ]
    },
    "payload": {}
  }
}

Report state with ChangeReport events

You send ChangeReport events to proactively notify Alexa of any state changes and to ensure the Alexa app reflects the current device state. For example, when a customer manually switches on a light bulb endpoint, you notify Alexa by sending a ChangeReport event that indicates the powerState property of the Alexa.PowerController interface has changed its value to ON.

You send change reports to the event gateway. This requires that you request permission to send events to the gateway and that you store authentication information for each customer, which you include in the scope of the ChangeReport. For more information, see Authenticate a Customer to Alexa with Permissions.

If a property is specified as proactivelyReported during discovery, you must send Alexa a ChangeReport event whenever that property value changes.

  • Use the payload of the ChangeReport to provide the new property value and the reason for the change.
  • We recommend that you use the context of a ChangeReport to report the state of any additional properties not directly affected by the change. This helps make sure that the state of your device's properties are up-to-date, and can improve the customer experience.
  • If multiple properties were affected by a change, you can send Alexa a single ChangeReport event that contains a payload with multiple property values. You can also send multiple ChangeReport events that each contain a payload with a single property, though this is not recommended.

The following example shows a ChangeReport event for an endpoint that implements the Alexa.PowerController and Alexa.BrightnessController interfaces. The event reports that the endpoint changed its brightness value to 85% due to a physical interaction with the device, and it reports the powerState in the context object because the power state did not change.

{
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "namespace": "Alexa",
      "name": "ChangeReport",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "endpoint-001",
      "cookie": {
        "path": "path/for/this/endpoint"
      }
    },
    "context": {
      "properties": [
        {
          "namespace": "Alexa.PowerController",
          "name": "powerState",
          "value": "ON",
          "timeOfSample": "2017-02-03T16:20:50.52Z",
          "uncertaintyInMilliseconds": 60000
        },
        {
          "namespace": "Alexa.EndpointHealth",
          "name": "connectivity",
          "value": {
            "value": "OK"
          },
          "timeOfSample": "2017-02-03T16:20:50.52Z",
          "uncertaintyInMilliseconds": 0
        }
      ]
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.BrightnessController",
            "name": "brightness",
            "value": 85,
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

Payload details

The payload of a ChangeReport event specifies a change object that contains an array of changed properties and a cause object that specifies a reason for the change.

Cause Object

The cause attribute is used to describe the cause of a property value change when you send a ChangeReport event.

Cause Type Description
APP_INTERACTION Indicates that the event was caused by a customer interaction with an application. For example, a customer switches on a light or locks a door using the Alexa app or an app provided by a device vendor.
PHYSICAL_INTERACTION Indicates that the event was caused by a physical interaction with an endpoint. For example, manually switching on a light or manually locking a door lock.
PERIODIC_POLL Indicates that the event was caused by the periodic poll of an endpoint, which found a change in value. For example, you might poll a temperature sensor every hour and send the updated temperature to Alexa.
RULE_TRIGGER Indicates that the event was caused by the application of a device rule. For example, a customer 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 Indicates that the event was caused by a voice interaction. For example, a user speaking to their Echo device.

Property schemas

The schemas for all supported property types are documented in Property Schemas. The mapping of capability interfaces to properties, and the mapping of each property to its schema, is documented in each interface.

Report the state of endpoints asynchronously

You can send all of the messages that include state information to Alexa asynchronously. However, you must check each interface to make sure it supports asynchronous messaging.

For details about how to configure your skill to respond asynchronously, see Send Events to the Event Gateway.