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
- Prerequisites
- Notify Alexa of new or updated devices
- Notify Alexa of deleted devices
- Handle errors
- Related topics
Introduction
Proactive endpoint management means that when a customer adds, updates, or deletes a device from their account, you proactively send a message to notify Alexa. 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 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 the endpoints associated with that customer. 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 have to delete the devices in the Alexa app.
Prerequisites
To enable proactive endpoint management, you must have and be able to do the following:
- An existing Smart Home skill
- Retrieve and store authentication tokens for the customer
- Send events to the Alexa event gateway
Notify Alexa of new or updated devices
Send an AddOrUpdateReport when a user adds an endpoint, or renames or updates an existing endpoint. You can include all the endpoints associated with the user account, or only the new or updated endpoints. You can choose based on your skill implementation.
Notify Alexa of deleted devices
Send a DeleteReport when a user deletes a device from their account.
Handle errors
If the Alexa event gateway successfully accepts your AddOrUpdateReport or DeleteReport event, you receive an HTTP 202 response. Otherwise, you receive one of the errors described in Event gateway error codes. Follow the instructions to help diagnose and fix the issue.
