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 in your system. Typically, the skill includes the access token in a request to your device cloud to retrieve the devices associated with the customer account. Your cloud returns the list of known devices for the customer.

In the discovery response, you describe the device endpoints, the capabilities of each endpoint, and configuration for any interfaces that require it. You can find example discovery responses in the documentation for each interface. For detailed examples 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": "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.

Mark each reportable property as retrievable = true and proactivelyReported = true for the Alexa interfaces that your skill supports. In addition, set the displayCategories property to the one that's most appropriate for your device. Alexa notifies users about the state of their devices by voice, in the Alexa app, and on Alexa-enabled devices with a screen. 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.BrightnessController",
            "version": "3",
            "properties": {
                "supported": [{
                    "name": "brightness"
                }],
                "proactivelyReported": true,
                "retrievable": true
            }
        },
        {
            "type": "AlexaInterface",
            "interface": "Alexa.EndpointHealth",
            "version": "3.1",
            "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 an endpoint, you proactively notify Alexa of the change. You send the details of the change as an asynchronous event to the Alexa event gateway. When you implement proactive updates for new endpoints, 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.

Identify relationships between endpoints

When linked devices display in the Alexa app as multiple devices, it can cause confusion to customers when they view devices separately or try to add devices to a group. Linked devices might include the following examples:

  • Compound devices, such as Alexa Built-in (ABI) devices with a smart home skill
  • Smart home products with multiple endpoints
  • Scenes with multiple endpoints

You can report relationships between linked devices by including the Relationships object in your discovery response and proactive update events. Then, related devices display under a parent device in the Alexa app. And, when the customer adds the parent to a group, all related devices move together. For example, if the parent is an ABI endpoint, the ABI name displays in the Alexa app. If the parent is a smart home device, the friendly name of the endpoint displays in the Alexa app.

Example video devices controlled by an Alexa Built-in endpoint

In the following example, the reported relationships associate smart home endpoints with video capability with an ABI device. Here, the ABI device controls the soundbar and TV. As a result, Alexa receives two separate messages: Discover.Response from the video skill and AddOrUpdateReport from the ABI device.

The example uses the following endpoint IDs:

  • ABI Alexa-enabled hub: ABI-hub-endpointID
  • Smart home soundbar: soundbar-endpointID
  • TV: tv-endpointID

Example home theater

In the following example, the reported relationships associate multiple smart home endpoints into a home theater pairing. Here, the smart home sound bar controls the ABI speakers and the TV. The example uses the following endpoint IDs:

  • ABI speakers: speaker-endpoint-00X
  • Smart home soundbar: soundbar-endpointID
  • TV: tv-endpointID

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "AddOrUpdateReport",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "scope": {
                "type": "BearerToken",
                "token": "sometoken.1"
            },
            "endpoints": [{
                    "endpointId": "soundbar-endpointID",
                    "friendlyName": "Living Room",
                    "displayCategories": ["SPEAKER"],
                    "relationships": {
                        "isClusterOf": [
                            {
                            "endpointId": "ABI-speaker-001",
                            "endpointTypeId": "speaker-productId-001",
                            "source": "AVS"
                            },
                            {
                            "endpointId": "ABI-speaker-002",
                            "endpointTypeId": "speaker-productId-001",
                            "source": "AVS"
                            },
                            {
                            "endpointId": "ABI-soundbar-001",
                            "endpointTypeId": "soundbar-productId-001",
                            "source": "AVS"
                            }
                        ]
                    }
                },
                {
                    "endpointId": "tv-endpointID",
                    "friendlyName": "TV",
                    "displayCategories": ["TV"],
                    "relationships": {
                        "isControlledBy": [{
                            "endpointId": "soundbar-endpointID"
                        }]
                    }
                }
            ]
        }
    }
}
Was this page helpful?

Last updated: Jul 01, 2024