Alexa.Discovery Interface 3
The Alexa.Discovery
interface describes messages used to identify the endpoints associated with the customer's device account. You respond to discovery directives so that Alexa can discover the endpoints associated with your smart home skill, and you send events proactively to add, update or delete endpoints associated with a customer account.
For an overview of discovery, see About Alexa Discovery.
Interface limits
The discovery interface has the following limits for each customer:
- Maximum number of endpoints – 300
- Maximum number of capabilities for each endpoint – 100
- Maximum payload size for
AddOrUpdateReport
event – 256 kilobytes (KB)
Utterances
The Alexa.Discovery interface uses the pre-built voice interaction model. The following examples show some user utterances:
اليكسا، اكتشف أجهزتي
Alexa, ontdek mijn apparaten.
Alexa, discover my smart home devices.
Alexa, finde meine smarten Geräte.
Alexa, découvre mes appareils.
Alexa, मेरे उपकरण खोजें.
Alexa, scopri miei dispositivi.
アレクサ、デバイスを検出して
Alexa, descubra meus dispositivos.
Alexa, descubre mis dispositivos.
Directives and events
Discover directive
Support the Discover
directive so that customers find smart devices associated with their account. Users can ask Alexa to discover their devices, or they can open the Alexa app and choose discover devices.
Discover directive example
The following example illustrates a Discover
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"payload": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
}
}
}
}
Discover directive payload details
Field | Description | Type |
---|---|---|
scope |
Provides authorization and identifying information for the request. Use the access token to identify the customer in your system. | Scope object |
Discover response
If you handle a Discover
directive successfully, respond with a Discover.Response
. In your response, return all the endpoints associated with the customer's device cloud account, and the capabilities that your skill supports for each device. To enable Alexa to identify unique devices, include the AdditionalAttributes
object and set as many fields as you can. Amazon recommends that you include at least model and manufacturer.
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.
Discover response example
The following example shows a Discover.Response
message for a light that supports the Alexa.PowerController
and Alexa.BrightnessController
interfaces. To see example discover responses for other capabilities, see the documentation for each interface, and Additional Discovery Response Examples. In your list of supported capabilities, include Alexa.EndpointHealth
so that Alexa can notify the user when a device experiences a health issue, such as loss of connectivity. Also, you must include the Alexa
interface for all endpoints.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "Unique ID of the endpoint",
"manufacturerName": "Sample Manufacturer",
"description": "Smart Light by Sample Manufacturer",
"friendlyName": "Living Room 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"
},
"displayCategories": ["LIGHT"],
"cookie": {},
"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"
}
],
"connections": [
{
"type": "TCP_IP",
"macAddress": "00:11:22:AA:BB:33:44:55"
},
{
"type": "MATTER",
"macAddress": "00:11:22:AA:BB:33:44:55",
"macNetworkInterface": "WIFI",
"matterVendorId": "Matter VendorID",
"matterProductId": "Matter ProductID",
"matterDiscriminator": "longDiscriminator"
}
]
}]
}
}
}
Discover response payload
Field | Description | Type | Required |
---|---|---|---|
endpoints |
Devices associated with the customer's account, and the capabilities that your skill supports for each device. If there are no devices associated with the customer account, return an empty array for this property. The endpoints field is subject to size limits. |
Array of Endpoint objects |
Yes |
Discover directive error handling
If you can't handle a Discover
directive successfully, respond with an Alexa.ErrorResponse
event. Use one of the following error types as appropriate: BRIDGE_UNREACHABLE
, EXPIRED_AUTHORIZATION_CREDENTIAL
, INSUFFICIENT_PERMISSIONS
, INTERNAL_ERROR
, INVALID_AUTHORIZATION_CREDENTIAL
.
AddOrUpdateReport event
You send an AddOrUpdateReport
event proactively when a customer adds a new endpoint to their account, or makes changes to an existing endpoint, such as renaming a scene. Send your AddOrUpdateReport
event to the Alexa event gateway. You can include all the endpoints associated with the customer account, or only the new or updated endpoints. You can choose based on your skill implementation.
AddOrUpdateReport event example
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": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "Unique ID of the endpoint",
"manufacturerName": "Sample Manufacturer",
"description": "Smart Light by Sample Manufacturer",
"friendlyName": "Kitchen 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"
},
"displayCategories": ["LIGHT"],
"cookie": {},
"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"
}
],
"connections": [{
"type": "BLUETOOTH_MESH",
"deviceUuid": "90b6eeb8cb58c9a7887d4797543bbe8a"
}]
}],
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
}
}
}
}
AddOrUpdateReport event payload
Field | Description | Type | Required |
---|---|---|---|
endpoints |
Devices associated with the customer's account, and the capabilities that your skill supports for them. If there are no devices associated with the customer account, return an empty array for this property. The endpoints array is subject to size limits. |
Array of Endpoint objects |
Yes |
scope |
Contains a bearer token to identify the customer to Alexa. | Scope object |
Yes |
DeleteReport event
You send a DeleteReport
event proactively when a customer removes an endpoint from their account. Send your DeleteReport
message to the Alexa event gateway.
DeleteReport event example
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": "DeleteReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"payload": {
"endpoints": [
{
"endpointId": "endpoint id 1"
},
{
"endpointId": "endpoint id 2"
}
],
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
}
}
}
}
DeleteReport event payload
Field | Description | Type | Required |
---|---|---|---|
endpoints |
Endpoints to delete from the customer account. Use a valid endpointId that you defined in the Discover.Response or AddOrUpdateReport event. |
Array of strings | Yes |
scope |
Contains a bearer token to identify the customer to Alexa. | Scope object |
Yes |
Display categories
When you provide the display category in your discovery response, your endpoint appears in the correct category in the Alexa app, with the correct iconography. The category makes it easier for customers to find and monitor your devices. Set the displayCategories
property to the one that's most appropriate for your device.
Value | Description |
---|---|
ACTIVITY_TRIGGER |
Combination of devices set to a specific state. Use activity triggers for scenes when the state changes must occur in a specific order. For example, for a scene named "watch Netflix" you might power on the TV first, and then set the input to HDMI1. |
AIR_CONDITIONER |
Device that cools the air in interior spaces. |
AIR_FRESHENER |
Device that emits pleasant odors and masks unpleasant odors in interior spaces. |
AIR_PURIFIER |
Device that improves the quality of air in interior spaces. |
AIR_QUALITY_MONITOR |
Device that measures air quality in interior spaces. |
ALEXA_VOICE_ENABLED |
Device with Alexa Built-in. |
AUTO_ACCESSORY |
Smart device in an automobile, such as a dash camera. |
BLUETOOTH_SPEAKER |
Speaker that connects to an audio source over Bluetooth. |
CAMERA |
Security device with video or photo functionality. |
CHRISTMAS_TREE |
Religious holiday decoration that often contains lights. |
COFFEE_MAKER |
Device that makes coffee. |
COMPUTER |
Non-mobile computer, such as a desktop computer. |
CONTACT_SENSOR |
Endpoint that detects and reports changes in contact between two surfaces. |
DISHWASHER |
Appliance that cleans dishes. |
DOOR |
Endpoint that allows entrance to a building, room, closet, cupboard, or vehicle. |
DOORBELL |
Smart doorbell. |
DRYER |
Appliance that dries wet clothing. |
EXTERIOR_BLIND |
Window covering, such as blinds or shades, on the outside of a structure. |
FAN |
Device for cooling or ventilation. |
GAME_CONSOLE |
Video game console, such as Microsoft Xbox or Nintendo Switch |
GARAGE_DOOR |
Endpoint that allows vehicles to enter a garage. Garage doors must implement the Alexa.ModeController interface to open and close the door. |
HEADPHONES |
Wearable device that transmits audio directly into the ear. |
HUB |
Smart-home hub. |
INTERIOR_BLIND |
Window covering, such as blinds or shades, on the inside of a structure. |
LAPTOP |
Laptop or other mobile computer. |
LIGHT |
Light source or fixture. |
MICROWAVE |
Microwave oven cooking appliance. |
MOBILE_PHONE |
Mobile phone. |
MOTION_SENSOR |
Endpoint that detects and reports movement in an area. |
MUSIC_SYSTEM |
Network-connected music system. |
NETWORK_HARDWARE |
Network router. |
OTHER |
Endpoint that doesn't belong to one of the other categories. |
OVEN |
Oven cooking appliance. |
PHONE |
Non-mobile phone, such as landline or an IP phone. |
PRINTER |
Device that prints. |
REMOTE |
Devices that support stateless events, such as remote switches and smart buttons. |
ROUTER |
Network router. |
SCENE_TRIGGER |
Combination of devices set to a specific state. Use scene triggers for scenes when the order of the state change isn't important. For example, for a scene named "bedtime" you might turn off the lights and lower the thermostat, in any order. |
SCREEN |
Projector screen. |
SECURITY_PANEL |
Security panel. |
SECURITY_SYSTEM |
Security system. |
SLOW_COOKER |
Electric cooking appliance that sits on a counter top, cooks at low temperatures, and is often shaped like a cooking pot. |
SMARTLOCK |
Endpoint that locks. |
SMARTPLUG |
Module plugged into an existing electrical outlet, and then has a device plugged into it. For example, a customer can plug a smart plug into an outlet, and then plug a lamp into the smart plug. A smart plug can control a variety of devices. |
SPEAKER |
Speaker or speaker system. |
STREAMING_DEVICE |
Streaming device, such as Apple TV, Chromecast, or Roku. |
SWITCH |
Switch wired directly to the electrical system. A switch can control a variety of devices. |
TABLET |
Tablet computer. |
TEMPERATURE_SENSOR |
Endpoint that reports temperature, but doesn't control it. The temperature data of the endpoint doesn't appear in the Alexa app. If your endpoint also controls temperature, use THERMOSTAT instead. |
THERMOSTAT |
Endpoint that controls temperature, stand-alone air conditioners, or heaters with direct temperature control. If your endpoint senses temperature but doesn't control it, use TEMPERATURE_SENSOR instead. |
TV |
Television. |
VACUUM_CLEANER |
Vacuum cleaner. |
VEHICLE |
Motor vehicle (automobile, car). |
WASHER |
Appliance that cleans clothing. |
WATER_HEATER |
Device that heats water, often consisting of a large tank. |
WEARABLE |
Network-connected wearable device, such as an Apple Watch, Fitbit, or Samsung Gear. |
Related topics
- Alexa Discovery Objects
- Discovery Response Examples
- Friendly Name Resources and Assets
- Alexa Interface Message and Property Reference
Last updated: Jul 01, 2024