Alexa.EndpointHealth Interface 3.1

Implement the Alexa.EndpointHealth interface in your Alexa add-on so that you can report the detected health of devices to Alexa. When a device encounters an issue, you report the reason so that Alexa can inform the customer of device degradation, such as connectivity failure due to Wi-Fi password change. You implement the Alexa.EndpointHealth interface with other interfaces that provide functionality for your device. For example, if your device is a thermostat, you implement Alexa.ThermostatController so the user can control the thermostat, Alexa.TemperatureSensor so the thermostat can sense and report temperature, and Alexa.EndpointHealth so that you can report the connectivity status of the thermostat. Although Alexa.EndpointHealth is optional for most device types, Amazon recommends that you always implement the interface to provide the best experience for customers. For sensor devices, such as motion sensors and temperature sensors, Alexa.EndpointHealth is a required capability. For the list of languages that the Alexa.EndpointHealth interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

The Alexa.EndpointHealth interface doesn’t have any user utterances. Instead, when the user tries to control their device, Alexa responds with information about the health of the device. For example, when an add-on reports that a plug is unreachable and the user tries to turn on the plug, Alexa responds with

Reportable properties

The Alexa.EndpointHealth interface includes the following reportable property.

Connectivity property

The connectivity property represents the connectivity status of a device. connectivity is a required property. When you report UNREACHABLE, Alexa responds to a request to control the device with a response similar to the following examples. The connectivity failure reason isn’t given in the response.

The following example shows an unreachable device.

{
    "name": "connectivity",
    "value": {
        "value": "UNREACHABLE",
        "reason": "WIFI_BAD_PASSWORD"
    }
}

The connectivity property is an object that contains the following fields.

Field	Description	Type
`value`	The connectivity status of the device. Valid values: `OK`, `UNREACHABLE`.	String
`reason`	(Optional) When the device is unreachable, this property gives the failure reason. For valid values, see connectivity reasons.	String

Connectivity reason values

The following table shows the valid values, descriptions, and possible resolutions for each connectivity failure reason.

Value	Description
`WIFI_BAD_PASSWORD`	The device failed to connect to Wi-Fi due to a bad password.
`WIFI_AP_NOT_FOUND`	The device can’t find the Wi-Fi access point. The device might be too far from the router or near another device that causes interference, such as a baby monitor, microwave, or other electronic device.
`WIFI_ROUTER_UNREACHABLE`	The device can’t send data to the router, or receive data from the router. The internet might be down or the router might need a reboot.
`WIFI_AP_CHANNEL_QUALITY_LOW`	The device can connect to the access point, but the channel quality is low.
`INTERNET_UNREACHABLE`	The device can connect to the access point, but doesn’t have internet access. The router or device might need a reboot, or the internet might be down.
`CAPTIVE_PORTAL_CHECK_FAILED`	The device is trying to connect to a captive portal. The interface doesn’t support captive portals. Airports and hotels commonly use captive portal networks. These networks ask the user to agree to specific terms before connecting to the network. The customer must select a different network.
`UNKNOWN`	The reason for connectivity failure isn’t known.

Discovery

You describe endpoints that support the Alexa.EndpointHealth interface by using the standard discovery mechanism described in Alexa.Discovery. Set retrievable to true for all the properties that you report when Alexa sends your add-on a state report request. Set proactivelyReported to true for properties that you proactively report to Alexa in a change report. When you implement Alexa.EndpointHealth, set retrievable to true and proactivelyReported to true for the properties that you support.

Discover response example

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

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "Unique ID of the endpoint",
                "manufacturerName": "Sample Manufacturer",
                "description": "Description to be shown in the Alexa app",
                "friendlyName": "Your device name, displayed in the Alexa app, for example Front Door>",
                "displayCategories": ["SMARTLOCK"],
                "additionalAttributes": {
                    "manufacturer": "Sample Manufacturer",
                    "model": "Sample Model",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.LockController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "lockState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.1",
                        "properties": {
                            "supported": [{
                                    "name": "connectivity"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Directives

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

Directive response event example

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

Endpoint healthy example

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
          "scope": {
            "type": "BearerToken",
            "token": "OAuth2.0 bearer token"
          },
          "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-03T08:00:00.10Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

Endpoint unreachable example

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
          "scope": {
            "type": "BearerToken",
            "token": "OAuth2.0 bearer token"
          },
          "endpointId": "Endpoint ID"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.PowerController",
                "name": "powerState",
                "value": "ON",
                "timeOfSample": "2017-02-03T16:22:45.12Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "UNREACHABLE",
                    "reason": "WIFI_ROUTER_UNREACHABLE"
                },
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

State reporting

Alexa sends an Alexa.ReportState directive to request information about the state of an endpoint. When Alexa sends an Alexa.ReportState directive, you send an Alexa.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 Alexa.EndpointHealth, include the connectivity property in your Alexa.StateReport.

StateReport response example

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

State reporting example

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "StateReport",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
          "scope": {
            "type": "BearerToken",
            "token": "OAuth2.0 bearer token"
          },
          "endpointId": "Endpoint ID"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.ThermostatController",
                "name": "thermostatMode",
                "value": "HEAT",
                "timeOfSample": "2017-01-01T08:00:00.10Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "targetSetpoint",
                "value": {
                    "value": 20.0,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2017-01-01T08:00:00.10Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.TemperatureSensor",
                "name": "temperature",
                "value": {
                    "value": 19.9,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2017-02-03T16:22:50.52Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

Change reporting

To report changes proactively in the state of an endpoint, you send an Alexa.ChangeReport event. You identify the properties that you report proactively in your discovery response. For details about change reports, see Understand State and Change Reporting. When you implement Alexa.EndpointHealth, include the connectivity property in your Alexa.ChangeReport. If the value of the connectivity property has changed, put it in the payload field. If the value of the connectivity property hasn’t changed, put it in the context field.

Report unchanged device health

The following example shows an Alexa.ChangeReport for an endpoint that supports the Alexa.EndpointHealth and Alexa.LockController interfaces. In this change report, only the lockState property value changed.

Endpoint unchanged example

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "ChangeReport",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2.0 bearer token"
            },
            "endpointId": "Endpoint ID"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "APP_INTERACTION"
                },
                "properties": [{
                    "namespace": "Alexa.LockController",
                    "name": "lockState",
                    "value": "LOCKED",
                    "timeOfSample": "2021-10-15T14:20:00.00Z",
                    "uncertaintyInMilliseconds": 1000
                }]
            }
        }
    },
    "context": {
        "properties": [{
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
                "value": "OK"
            },
            "timeOfSample": "2021-10-15T14:15:00.00Z",
            "uncertaintyInMilliseconds": 0
        }]
    }
}

Report changed device health

Endpoint changed example

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "ChangeReport",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2.0 bearer token"
            },
            "endpointId": "Endpoint ID"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "PERIODIC_POLL"
                },
                "properties": [{
                    "namespace": "Alexa.EndpointHealth",
                    "name": "connectivity",
                    "value": {
                        "value": "UNREACHABLE",
                        "reason": "INTERNET_UNREACHABLE"
                    },
                    "timeOfSample": "2021-11-15T14:21:00.00Z",
                    "uncertaintyInMilliseconds": 0
                }]
            }
        }
    },
    "context": {
        "properties": [{
            "namespace": "Alexa.LockController",
            "name": "lockState",
            "value": "LOCKED",
            "timeOfSample": "2021-11-15T08:20:00.00Z",
            "uncertaintyInMilliseconds": 60000
        }]
    }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Utterances

Reportable properties

Connectivity property

Connectivity reason values

Discovery

Discover response example

Directives

Directive response event example

State reporting

StateReport response example

Change reporting

Report unchanged device health

Report changed device health

​Utterances

​Reportable properties

​Connectivity property

​Connectivity reason values

​Discovery

​Discover response example

​Directives

​Directive response event example

​State reporting

​StateReport response example

​Change reporting

​Report unchanged device health

​Report changed device health

​Related topics

Utterances

Reportable properties

Connectivity property

Connectivity reason values

Discovery

Discover response example

Directives

Directive response event example

State reporting

StateReport response example

Change reporting

Report unchanged device health

Report changed device health

Related topics