Vielen Dank für Ihren Besuch. Diese Seite ist momentan nur auf Englisch verfügbar. Wir arbeiten an der deutschen Version. Vielen Dank für Ihr Verständnis.

Alexa.EndpointHealth Interface

The Alexa.EndpointHealth interface defines a series of state properties representing information about the overall health of a smart device.

This interface enables in-depth reporting of the state of devices, which are reported to the customer through experiences like the Alexa app. For example, the app could show a green, yellow or red status for a device depending on the state of its EndpointHealth properties.

Discovery

You must report whether you support the properties defined in this interface in a discovery response.

The following code example shows how an endpoint reports its support for the EndpointHealth properties. For more information on device discovery messages, see Alexa.Discovery

{
   "event":{
      "header":{
         "namespace":"Alexa.Discovery",
         "name":"Discover.Response",
         "payloadVersion":"3",
         "messageId":"abc-123-def-456"
      },
      "payload":{
         "endpoints":[
            {
               "endpointId":"appliance-002",
               "friendlyName":"Hallway Thermostat",
               "description":"Smart Thermostat by Sample Manufacturer",
               "manufacturerName":"Sample Manufacturer",
               "displayCategories":[
                  "THERMOSTAT"
               ],
               "cookie":{

               },
               "capabilities":[
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.EndpointHealth",
                     "version":"3",
                     "properties":{
                        "supported":[
                           {
                              "name":"connectivity"
                           }
                        ],
                        "proactivelyReported":true,
                        "retrievable":true
                     }
                  },
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.ThermostatController",
                     "version":"3",
                     "properties":{
                        "supported":[
                           {
                              "name":"targetSetpoint"
                           },
                           {
                              "name":"thermostatMode"
                           }
                        ],
                        "proactivelyReported":true,
                        "retrievable":true
                     }
                  },
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.TemperatureSensor",
                     "version":"3",
                     "properties":{
                        "supported":[
                           {
                              "name":"temperature"
                           }
                        ],
                        "proactivelyReported":false,
                        "retrievable":true
                     }
                  }
               ]
            }
         ]
      }
   }
}

Directives

This interface does not define any directives.

Properties and Events

You report the value of properties in this interface in one of the following ways:

Properties

Property Name Type Description
connectivity connectivity Specifies the status of the communication path between the hub or cloud and the device. Supported values are: OK, UNREACHABLE

Additional properties may be added at a later date.

ChangeReport

If your endpoint supports a property as proactivelyReported, then you should report its value to Alexa if it changes for some reason.

Example ChangeReport


POST /v3/events HTTP/1.1
Host: api-amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json

{
   "context":{ },
   "event":{
      "header":{
         "messageId":"abc-123-def-456",
         "namespace":"Alexa",
         "name":"ChangeReport",
         "payloadVersion":"3"
      },
      "endpoint":{
        "scope": {
          "type":"BearerToken",
          "token":"access-token-from-Amazon"
         },
         "endpointId":"<the endpoint identifier of the endpoint >"
      },
      "payload":{
         "change":{
            "cause":{
               "type":"PHYSICAL_INTERACTION"
            },
            "properties":[
               {
                  "namespace":"Alexa.EndpointHealth",
                  "name":"connectivity",
                  "value":{
                     "value":"UNREACHABLE"
                  },
                  "timeOfSample": "2017-02-03T16:20:50.52Z",
                  "uncertaintyInMilliseconds": 0
               }

            ]
         }
      }
   }
}

StateReport

If your endpoint supports a property as retrievable, then you should report its value when you receive a ReportState directive from Alexa.

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

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