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 add-on, 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:

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 add-on.

{
  "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 add-on 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 add-on 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 add-on 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 add-on 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 add-on 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`	Device that supports 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 countertop, 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.
`VACUUM`	Vacuum cleaner or other type of vacuum.
`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.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Interface limits

Utterances

Directives and events

Discover directive

Discover directive example

Discover directive payload details

Discover response

Discover response example

Discover response payload

Discover directive error handling

AddOrUpdateReport event

AddOrUpdateReport event example

AddOrUpdateReport event payload

DeleteReport event

DeleteReport event example

DeleteReport event payload

Display categories

​Interface limits

​Utterances

​Directives and events

​Discover directive

​Discover directive example

​Discover directive payload details

​Discover response

​Discover response example

​Discover response payload

​Discover directive error handling

​AddOrUpdateReport event

​AddOrUpdateReport event example

​AddOrUpdateReport event payload

​DeleteReport event

​DeleteReport event example

​DeleteReport event payload

​Display categories

​Related topics

Interface limits

Utterances

Directives and events

Discover directive

Discover directive example

Discover directive payload details

Discover response

Discover response example

Discover response payload

Discover directive error handling

AddOrUpdateReport event

AddOrUpdateReport event example

AddOrUpdateReport event payload

DeleteReport event

DeleteReport event example

DeleteReport event payload

Display categories

Related topics