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":"5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
      },
      "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:

Reportable 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 proactivelyReportable, then you should report its value to Alexa if it changes for some reason.

Example ChangeReport

{
   "context":{ },
   "event":{
      "header":{
         "messageId":"abc-123-def-456",
         "namespace":"Alexa",
         "name":"ChangeReport",
         "payloadVersion":"3"
      },
      "endpoint":{
         "scope":{
            "type":"AlexaUserId",
            "userId":"some-Amazon-user-id"
         },
         "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.

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 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": "some-access-token"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}