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 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:

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.