Your Alexa Dashboards Settings

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 and in the Alexa app.

You must indicate the level of state reporting you support in your discovery response. You can then report the state of endpoint properties in the following ways:

  1. In response events with the context object: You report state when you respond to a control directive. When you send a Response event you are indicating the request completed successfully, and you report the state of any changed properties in the context object of the response. You can include additional properties that you think may have changed. For example, when responding to a TurnOn directive, you send a Response event that includes the state of the power property, but may include the state of all of the properties of the endpoint. You can send response events synchronously from the Lambda function or asynchronously to the event gateway.
  2. In change notification events: If the state of an endpoint has changed and its not the result of a directive, you report that change to Alexa in a ChangeReport event. Alexa can then provide that status change to the customer. For example a light is manually switched on, you send a change report indicating the power is on to Alexa, and Alexa provides this status change to the customer. You can also optionally report the state of other (non-changed) properties in the context object. Note that to send ChangeReport events, you must request permission to send events to the event gateway and obtains authentication tokens for each customer, which you include in the scope of the event message.
  3. When Alexa requests the current state: Alexa sends a ReportState directive requesting an update on 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 reportable. 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 reportable properties for that endpoint. You can send a StateReport synchronously from the Lambda function or asynchronously to the event gateway.

Indicating state reporting support during discovery

To enable this state reporting, you indicate the level of state reporting an endpoint provides for each property at discovery. You list the properties and what level of state reporting they support with the retrievable and proactivelyReported attributes, which are both boolean values.

  • retrievable means an endpoint’s properties can be queried for their current state.
  • proactivelyReported means you send change notification events for an endpoint, which are not the result of a customer request to Alexa. This requires access to the event gateway and that you have completed the authentication flow to store tokens for every customer. For more information, see Authenticate a Customer to Alexa with Permissions.

There are four combinations of these values:

Property Values Description
"proactivelyReported": true, "retrievable": true Change notification events are sent and a property is queryable. For example a light bulb that supports querying of its state, and which also issues events on state changes caused by physical interactions with the device.
"proactivelyReported": false, "retrievable": true A property does not send change notification events, but it is queryable. An example of this is a light bulb that supports querying, but it does not issue events on physical interactions.
"proactivelyReported": true, "retrievable": false A property sends change notification events, but it cannot be queried. An example of this might be a low energy device. It is normally in a dormant state, so it cannot be queried, but it will activate when a setting changes and emits a change notification event
"proactivelyReported": false, "retrievable": false A property does not send change notification events or support query. An example of this might be an appliance which is controlled via an infra-red transmitter. Infrared is a one-way control mechanism. Commands can be sent to the appliance, but the appliance supports no mechanism for sending messages about its state. This is a non-queryable property.

Note that:

  • If you do not specify a property in the supported array, then the default behavior is to assume that proactivelyReported and retrievable for that property are false.
  • If the properties object is missing entirely, the default is to assume that no properties defined by the interface are queryable or provide change notification. By assuming false, it is less likely an error will occur.

New properties and directives can be added to an interface, but Alexa will not attempt to use these with an endpoint unless they are specified as supported during the discovery process.

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.PowerController",
            "version": "3",
            "properties": {
              "supported": [{
                "name": "powerState"
              }],
              "proactivelyReported": true,
              "retrievable": true
            }
          }
        ]
      }]
    }
  }
}

For more information, see Alexa.Discovery.

Report state with a context object in response events

Use the 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 may or may not have changed. See the Property Schemas topic to see what values you can report state for.

You can send a state information in a context when you receive a directive which has a state changing side-effect. 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 respond with a Response event, and include 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 ensure that the values reported incorporate all the side-effects from handling the request directive. This example shows an endpoint that implements the Alexa.PowerController and Alexa.BrightnessController interfaces. These responses include the same correlationToken in the message header that was present in the directive.


{
  "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
      }
    ]
  },
  "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": {}
  }
}

Property object

The property object communicates what property has changed, its new has changed and when. You describe the what properties are supported for an endpoint during discovery, and then send properties that contain state information in events. Context objects or the payload of a message could contain a property, but you should report the property in either the context or the payload, and not both.

Field Description
namespace Specifies the interface for the property
name The property name being reported
value The value for the property specified by name
timeOfSample The time at which the property value was provided in ISO 8601 format, and specified in UTC. Example: “YYYY-MM-DDThh:mm:ss.sD”
uncertaintyInMilliseconds Indicates the uncertainty of the reported property in milliseconds of elapsed time since the property value was retrieved. For example, if you obtain this value by polling a hardware device every 60 seconds, then the uncertainty in the time of the sampled value would be 60000 in milliseconds.

Please note that capability interfaces are free to implement interface specific or even directive specific success events if the simple one in the Alexa namespace is not sufficient for their needs.

Report state with change reports

ChangeReport events are sent to proactively notify Alexa of state changes and ensure the Alexa app reflects current device state. For example, a customer manually switches on the “Kitchen Light” endpoint, and you notify Alexa by sending a ChangeReport event that indicates the powerState property of the Alexa.PowerController interface has changed its value to “ON”.

Because you send change reports proactively, and not as the result of a customer voice interaction with Alexa, you must send them 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 change report scope. 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.
  • You can optionally use the context of a ChangeReport to report the state of any additional properties, if you think they may have changed, or would like to report the current state of all the properties.
  • If multiple properties have changed, you can send Alexa 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.

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

{
   "context":{
      "properties":[
         {
            "namespace":"Alexa.PowerController",
            "name":"powerState",
            "value":"ON",
            "timeOfSample":"2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds":60000
         }
      ]
   },
   "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"
         }
      },
      "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. It is a polymorphic type with the following descendant types:

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 appliance, 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 with Alexa. For example a user speaking to their Echo device.

More cause types will likely be added as the API matures.

Report state when Alexa requests it

When Alexa requests a state report for an endpoint, a ReportState directive is sent, specifying the endpoint for the state request. In this example, the endpoint implements the Alexa.ThermostatController capability interface. When you receive this message, you report state on all of the properties you define during the discovery process.

Example StateReport Request

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

When you reply you send a StateReport, which must include a context object that contains all of the 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.

It’s important to note that if the endpoint is currently unreachable, but you can report all endpoint property values because they are cached, return the a StateReport, include all of the property values, and indicate the connectivity property of EndpointHealth is UNREACHABLE. If you cannot report the state of all of the properties because the endpoint is unreachable, and you have not cached the values, you should send an ErrorResponse type of BRIDGE_UNREACHABLE or ENDPOINT_UNREACHABLE.

Example State Report Response

{
   "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
         }
      ]
   },
   "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":{

         }
      },
      "payload":{

      }
   }
}

Example StateReport for non-queryable powerState property

Upon successful handling of a TurnOn directive for an endpoint with properties that are not queryable, you send a Response event, but do not include the properties in the context.

In the following example, the empty properties array in the event context, in combination with the Response event name indicates to Alexa that the TurnOn request was successfully handled, but that the state after the change cannot be determined.

{
  "context": {
    "properties": [
    ]
  },
  "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"
    },
    "payload": {
    }
  }
}

Property schemas

The schemas for all supported property types is 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.

.