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:

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

When a user adds a new device, or makes updates to an existing one, you 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 to AddOrUpdateReport
  • 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.

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.
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment