Gracias por tu visita. Esta página solo está disponible en inglés.

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.

During device discovery, you must identify what state reporting you support for each property of your device. After device discovery, Alexa can request the state of your device properties, and you send the information back to Alexa in response events. Alexa requests endpoint state by sending you a control directive or a report state directive.

You can also proactively report state to Alexa as a change report event.

Indicate state reporting support during discovery

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

When you set retrievable=true for a property, it means that Alexa can query the property for its current state. To query for the state, Alexa sends a ReportState directive, and you respond with a StateReport event. If you don't specify retrievable, the default value is false.

When your set proactivelyReported=true for a property, it means that you send a ChangeReport event for the endpoint when the state of the property changes for any reason. If you don't specify proactivelyReported, the default value is 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 about device discovery, see Alexa.Discovery.

For each property, there are four combinations of retrievable and proactivelyReported:

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 response 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
              }
            }
          ]
        }
      ]
    }
  }
}

Property object

The property object communicates information about each property of an endpoint. You describe the properties that are supported for an endpoint during discovery, and then send properties and their state information in events.

Field Description
namespace The namespace of the property.
name The name of the property.
value The current value of the property.
timeOfSample The time at which the property value was recorded. Specify the time as a string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.
uncertaintyInMilliseconds The number of milliseconds that have elapsed since the property value was last confirmed. For example, if you last obtained this value 60 seconds ago, the uncertainty time is 60000.

Report state in response to a control directive

If Alexa sends a directive to change the state of a property, and you handle the directive successfully, send a response event. 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.

We recommend that you specify the state of all the properties of the endpoint, including the properties that didn't change, to help improve the customer experience.

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

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

Example response containing property state

{
    "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:50Z",
                "uncertaintyInMilliseconds": 0
            },
            {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 85,
                "timeOfSample": "2017-02-03T16:20:50Z",
                "uncertaintyInMilliseconds": 0
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2017-02-03T16:20:50Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

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

Report state in response to a ReportState directive

When Alexa sends a ReportState directive to request the state of an endpoint, you send a StateReport event in response. This response contains the current state of all of the properties that are retrievable in the context object.

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.

If you poll your endpoints periodically, you can send cached values for the properties in your response. If the endpoint is currently unreachable, but all property values 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 can't report the state of all the properties because the endpoint is unreachable and you have not cached the values, send an ErrorResponse of type BRIDGE_UNREACHABLE or ENDPOINT_UNREACHABLE.

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

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

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

Report state 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. 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 includes the powerState property, with its new value ON, in the payload.

If a property is specified 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 more information, see Report state in response to a control directive.

In the context object, specify the state of all the other properties of the endpoint that didn't change, to help improve the customer experience.

Example ChangeReport event

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. The event specifies the new brightness value in the payload, and it specifies the powerState property in the context object because the value 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"
            }
        },
        "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": "2017-02-03T16:20:50Z",
                "uncertaintyInMilliseconds": 60000
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2017-02-03T16:20:50Z",
                "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.