How to Proactively Manage Endpoints
Proactive endpoint management means that you can notify Alexa to add, update, or delete endpoints associated with your skill when a customer makes changes to their account with your service.
Introduction
Proactive endpoint management means that when a customer adds, updates or deletes a device from their account, you proactively send a message to let Alexa know to associate, update or disassociate this endpoint. This means customers can skip the discovery step and the device automatically appears in the Alexa app. For proactive discovery to work, the customer must have a smart home skill enabled and account-linked to an account with your system.
Previously when a customer added new endpoints, or made updates to existing endpoint, such as adding a new device or renaming a scene to their device account, they would ask Alexa to discover their devices or use the Alexa app. Then, Alexa sent a discovery request to all of the smart home skills enabled by that customer. The skill sent a response that described the endpoints associated with the customer account. Similarly, when a customer wanted to remove an endpoint they enabled with Alexa, they had to delete the endpoint in two places; from their account that managed the device, as well as in the Alexa app.
To add or update devices proactively, you send a message that contains details about the updated endpoints or all of the endpoints associated with that customer, similar to a discovery response. You send the message to the Alexa event gateway. To delete devices, you send a message that contains endpoint IDs to the event gateway. This means a customer doesn't need to delete the devices in the Alexa app.
Prerequisites
To enable proactive endpoint management, you should have an existing smart home skill that can send Alexa events, and has successfully retrieved and stored authentication tokens for the customer. For more information see the following topics:
- Steps to Build a Smart Home Skill
- Authenticate a Customer to Alexa with Permissions
- Send Events to the Alexa Event Gateway
Add code to send new events
You must add code to formulate messages and to do the following:
- Notify Alexa of new or updated devices - Send an
AddOrUpdateReport
when a user adds an endpoint, or an existing endpoint is updated or renamed - Notify Alexa of deleted devices- Send a
DeleteReport
when an endpoint is deleted from a customer account
Notify Alexa of new or updated devices
When a user adds a new device, or makes updates to an existing one, you will send an AddOrUpdateReport event, which has the same format as a discovery response. This message describes the capabilities and properties support for the endpoint. However there are distinct differences between an AddOrUpdateReport
event and a discovery response:
- The
name
of the message is set toAddOrUpdateReport
- The message includes a
scope
, which in turn includes a bearer token to identify the customer to Alexa, and an HTTP Authorization header that contains the same bearer token - The message is sent to the Alexa event gateway
- This message can include all of the endpoints associated with the customer account, or only the new or updated endpoints. You can choose based on your skill implementation.
Example: AddOrUpdateReport
Following is an example of an AddOrUpdateReport
that describes a light.
POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
},
"payload": {
"endpoints": [{
"endpointId": "appliance-001",
"friendlyName": "Living Room Light",
"description": "Smart Light by Sample Manufacturer",
"manufacturerName": "Sample Manufacturer",
"displayCategories": [
"LIGHT"
],
"cookie": {
"extraDetail1": "optionalDetailForSkillToReferenceThisDevice",
"extraDetail2": "There can be multiple entries",
"extraDetail3": "use for reference purposes",
"extraDetail4": "Do not use to maintain device state"
},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.ColorTemperatureController",
"version": "3",
"properties": {
"supported": [{
"name": "colorTemperatureInKelvin"
}],
"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"
},
{
"type": "AlexaInterface",
"interface": "Alexa.ColorController",
"version": "3",
"properties": {
"supported": [{
"name": "color"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [{
"name": "powerState"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.BrightnessController",
"version": "3",
"properties": {
"supported": [{
"name": "brightness"
}],
"proactivelyReported": true,
"retrievable": true
}
}
]
}],
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
}
}
}
}
Notify Alexa of deleted devices
When a customer deletes a device from their account, you send a DeleteReport event that contains a map of endpointIds
to delete devices from a customer account.
A delete report:
- Includes a
scope
, which in turn includes a bearer token to identify the customer to Alexa, and an HTTP Authorization token with the same bearer token. - Is sent to the Alexa event gateway
- Has a payload that contains a list of endpoint IDs, which identify the endpoints to delete
Example: DeleteReport
POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json
{
"event": {
"header": {
"messageId": "0a29824b-9299-4d55-b0c3-1d96ecfae81e",
"name": "DeleteReport",
"namespace": "Alexa.Discovery",
"payloadVersion": "3"
},
"payload": {
"endpoints": [{
"endpointId": "videoDevice-001"
},
{
"endpointId": "speaker-001"
}
],
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
}
}
}
}
Handle errors, if needed
If the AddOrUpdateReport
or DeleteReport
event is successfully accepted, you receive an HTTP 202 in response. Otherwise, you will receive one of the errors described in Send Events to the Alexa Event Gateway.
Follow the instructions to help diagnose and fix the issue.
Related topics
Topic | Description |
---|---|
Alexa.Discovery | Describes the discovery capability for smart home skills. |
Alexa.Authorization | Describes the capability for obtaining security tokens for Alexa customers |
Send Events to the Alexa Event Gateway | Describes how to send proactive/asynchronous messages to the Alexa event gateway. |