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
{
"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.
{
"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.
{
"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.
{
"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
.
connectivity
property has changed, put it in the payload field. If the value of the connectivity
property has not changed, put it in the context field.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.
{
"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.
{
"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
}
]
}
}