About Alexa Discovery

After a customer enables your smart home skill and links their device account with their Amazon account, they can ask Alexa to discover their devices. Alexa starts the discovery process with the enabled skill to learn about the customer's connected devices. You implement the Alexa discovery interface to identify the devices associated with the customer's device account. After discovery completes, customers can see a list of their devices in the Alexa app, and ask Alexa to control their devices.

Alexa uses the description of your device to automatically enable the pre-built voice interaction model for each capability. The model defines the user utterances to control the device. In addition, Alexa enables control of specified devices through the Alexa app and routines.

Discovery interface

When a customer enables a skill in the Alexa app or asks Alexa to discover devices, Alexa sends an Alexa.Discovery.Discover directive to your skill to request information about connected devices. Included in the request is an access token to associate the request with the customer account your system. In response, you describe the device endpoints, the capabilities of each endpoint, and a configuration for any interfaces that require it. The response includes all devices associated with the customer's device account.

For example discovery responses for specific device types, see Discovery Response Examples.

Identify the endpoint

An endpoint represents a connected device associated with a customer's device account. An endpoint describes one of the following:

  • A physical device
  • A virtual device
  • A group or cluster of devices, such as in a scene
  • A software component, such as a mobile app

For each endpoint, you define the unique ID of the endpoint and as much identifying information as possible, such as manufacturer, model, and serial number. Alexa uses this information to improve the user experience in the Alexa app. Also, you identify the display category and friendly name of each endpoint. The display category determines the icon and placement of your device in the Alexa app. Customers use the friendly name to identify the device to Alexa. Later, the customer can change the name in the Alexa app. For details about the Endpoint object, see Endpoint object definition.

The following example shows the description of a light endpoint.

Copied to clipboard.

{
    "endpointId": "unique ID of the endpoint",
    "manufacturerName": "Sample Manufacturer",
    "description": "Smart Light by Sample Manufacturer",
    "friendlyName": "Living Room Light",
    "displayCategories": ["LIGHT"],
    "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": "An optional custom identifier for the device"
    },
    "capabilities": [],
    "connections": [],
    "relationships": {},
    "cookie": {}
}

Declare device capabilities

For each endpoint, you include the capabilities of the endpoint in the discovery response. Capabilities define a device's functionality and you describe them by including the Smart Home API interface in the response. You include a combination of interfaces that best represent the endpoint features. For example, a light that you can turn on and off and dim might implement two interfaces: Alexa.PowerController and Alexa.BrightnessController. In your list of supported capabilities, you also include Alexa.EndpointHealth so that Alexa can notify the customer when a device experiences a health issue, such as low battery or loss of connectivity. Also, you must include the Alexa interface for all endpoints. For available Smart Home APIs, see List of Alexa Interfaces and Supported Languages.

For each capability interface, you indicate support for state and change reporting by setting the retrievable and proactivelyReported properties. Alexa notifies users about the state of their devices by voice or in the Alexa app. For details, see Understand State and Change Reporting.

The following example shows the capabilities of the light endpoint.

Copied to clipboard.

{
    "capabilities": [{
            "type": "AlexaInterface",
            "interface": "Alexa.PowerController",
            "version": "3",
            "properties": {
                "supported": [{ "name": "powerState" }],
                "proactivelyReported": true,
                "retrievable": true
            }
        },
        {
            "type": "AlexaInterface",
            "interface": "Alexa.EndpointHealth",
            "version": "3.2",
            "properties": {
                "supported": [{ "name": "connectivity" }],
                "proactivelyReported": true,
                "retrievable": true
            }
        },
        {
            "type": "AlexaInterface",
            "interface": "Alexa",
            "version": "3"
        }
    ]
}

Proactively manage endpoints

Proactive endpoint management keeps Alexa up to date with the customer's devices. When a customer adds, updates, or deletes a device from their device account, you send a message proactively to notify Alexa of the change. You send the message as an asynchronous event to the Alexa event gateway. When you implement proactive updates, customers can skip the discovery step and the device automatically appears in the Alexa app.

After a customer adds a new endpoint, or renames or updates an existing endpoint, you send an AddOrUpdateReport to notify Alexa of the new or updated device. Based on your skill implementation, you can include all the endpoints associated with the customer account, or only the new or updated endpoints.

After a customer deletes a device from their device account, you send a DeleteReport to notify Alexa that the device is no longer in use.