Alexa.EndpointHealth Interface

Implement the Alexa.EndpointHealth interface in your Alexa skill so that you can report the connectivity status of devices to Alexa. You implement the EndpointHealth interface in conjunction with other interfaces that provide functionality for your device. For example, if your device is a thermostat, you would implement ThermostatController so the user can control the thermostat, TemperatureSensor so the thermostat can sense and report temperature, and EndpointHealth so that you can report the connectivity status of the thermostat.

We recommend that you always implement EndpointHealth to provide the best experience for your users. Implementing EndpointHealth is optional, except in the following cases:

  • You must implement EndpointHealth for devices that are sensors, such as motion sensors and temperature sensors.
  • You must implement EndpointHealth for your device if you plan to pursue certification in the Works with Alexa or Certified for Humans program.

For the list of languages that the EndpointHealth interface supports, see List of Alexa Interfaces and Supported Languages.

Properties

The connectivity property

The Alexa.EndpointHealth interface uses the connectivity property to represent the connectivity of a device. The connectivity property is an object that contains the following fields.

Field Description Type
value The connectivity status of the device; one of OK or UNREACHABLE. String

Connectivity property example

Copied to clipboard.

{
    "name": "connectivity",
    "value": {
        "value": "OK"
    }
}

Discovery

You describe endpoints that support the Alexa.EndpointHealth interface using the standard discovery mechanism described in Alexa.Discovery.

Set retrievable to true for all the properties that you report when Alexa sends your skill a state report request. Set proactivelyReported to true for properties that you proactively report to Alexa in a change report. When you implement EndpointHealth, set retrievable to true and proactivelyReported to true for the connectivity property.

Discover response example

The following example shows a Discover.Response message for an endpoint that supports the EndpointHealth and LockController interfaces.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints":[
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<the manufacturer name of the endpoint>",
          "description": "<a description that appears in the Alexa app>",
          "friendlyName": "<device name, displayed in the Alexa app, for example Front Door>",
          "displayCategories": ["SMARTLOCK"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.LockController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "lockState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name":"connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directive responses

The Alexa.EndpointHealth interface does not define any directives itself. When you implement EndpointHealth, you must include the connectivity property when you respond to directives defined by other interfaces.

Directive response event example

In the following example, a device supports the PowerController and EndpointHealth interfaces, and is sending an Alexa.Response to the PowerController.TurnOn directive.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

State reporting

Alexa sends a ReportState directive to request information about the state of an endpoint. When Alexa sends a ReportState directive, you send a StateReport event in response. The response contains the current state of all retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see Understand State and Change Reporting.

When you implement EndpointHealth, include the connectivity property in your StateReport.

StateReport response event example

The following example shows a StateReport for an endpoint that supports the EndpointHealth, ThermostatController, and TemperatureSensor interfaces.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.9,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

Change reporting

You send a ChangeReport event to proactively report changes in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.

When you implement EndpointHealth, include the connectivity property in your ChangeReport.

ChangeReport event example with connectivity property unchanged

The following example shows a ChangeReport for an endpoint that supports the EndpointHealth and Networking.AccessController interfaces. In this change report, the value of the networkAccess property has changed, and the value of the connectivity property has not changed.

Copied to clipboard.

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "APP_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.Networking.AccessController",
            "name": "networkAccess",
            "value": "ALLOWED",
            "timeOfSample": "2019-10-15T14:20:00Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2019-10-15T14:20:00Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

ChangeReport event example with connectivity property changed

The following example shows a ChangeReport for an endpoint that supports the EndpointHealth and Networking.AccessController interfaces. In this change report, the value of the connectivity property has changed, and the value of the networkAccess property has not changed.

Copied to clipboard.

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PERIODIC_POLL"
        },
        "properties": [
          {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
              "value": "UNREACHABLE"
            },
            "timeOfSample": "2019-10-15T14:20:00Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.Networking.AccessController",
        "name": "networkAccess",
        "value": "ALLOWED",
        "timeOfSample": "2019-10-15T14:20:00Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}