Alexa.Discovery Interface

The Alexa.Discovery interface describes messages used to identify the endpoints associated with the user's device account. You respond to discovery directives so that a user can discover the devices and scenes associated with your Smart Home skill, and you should proactively send events to add, update or delete endpoints associated with a user account.

Limits

You skill must conform to the following limits for each user.

  • You can support at most 300 endpoints.
  • You can support at most 100 capabilities for each endpoint.
  • The payload for an AddOrUpdateReport event can be at most 256 kilobytes (KB).

Directives

Discover directive

Support the Discover directive so that users find the devices associated with their account. Users can ask Alexa to discover their devices, or they can open the Alexa app and choose discover devices.

The following example shows a user utterance:

Alexa, discover my smart home devices.

Alexa, finde meine smarten geräte.

Discover directive payload details

Field Description Type
scope Provides authorization and identifying information for the request. A scope object.

Discover directive example

The following example illustrates a Discover directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "payload": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      }
    }
  }
}

Discover response event

If you handle a Discover directive successfully, respond with an Discover.Response event. In your response, return all the devices associated with the user's device cloud account, and the capabilities that your skill supports for them.

Discover response event payload details

Field Description Type Required
endpoints The devices associated with the user's account, and the capabilities that your skill supports for them. If there are no devices associated with the user account, return an empty array for this property. The endpoints field is subject to size limits. An array of endpoint objects. Yes

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.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "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": "U11112233456",
            "firmwareVersion" : "1.24.2546",
            "softwareVersion": "1.036",
            "customIdentifier": "Sample custom ID"
          },
          "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",
              "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": "ZIGBEE",
              "macAddress": "00:11:22:33:44:55"
            },
            {
              "type": "ZWAVE",
              "homeId": "<0x00000000>",
              "nodeId": "<0x00>"
            },
            {
              "type": "UNKNOWN",
              "value": "00:11:22:33:44:55"
            }
          ]
        }
      ]
    }
  }
}

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 user adds a new endpoint to their account, or makes changes to an existing endpoint, such as renaming a scene. Send your AddOrUpdateReport message to the Alexa event gateway. You can include all the endpoints associated with the user account, or only the new or updated endpoints. You can choose based on your skill implementation.

AddOrUpdateReport event payload details

Field Description Type Required
endpoints The devices associated with the user's account, and the capabilities that your skill supports for them. If there are no devices associated with the user account, return an empty array for this property. The endpoints field is subject to size limits. An array of endpoint objects. Yes
scope An object containing a bearer token to identify the user to Alexa. A scope object. Yes

AddOrUpdateReport event example

Copied to clipboard.

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": "<message id>"
    },
    "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": "<the serial number of the device>",
            "firmwareVersion" : "<the firmware version of the device>",
            "softwareVersion": "<the software version of the device>",
            "customIdentifier": "<your 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
              }
            }
          ],
          "connections": [
          ]
        }
      ],
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      }
    }
  }
}

DeleteReport event

You send a DeleteReport event proactively when a user removes an endpoint from their account. Send your DeleteReport message to the Alexa event gateway.

DeleteReport event payload details

Field Description Type Required
endpoints The endpoints to delete from the user account. An array of endpoint ids. Yes
scope An object containing a bearer token to identify the user to Alexa. A scope object. Yes

DeleteReport event example

Copied to clipboard.

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": "<message id>",
        "payloadVersion": "3"
    },
    "payload": {
      "endpoints": [
          {
              "endpointId": "<endpoint id 1>"
          },
          {
              "endpointId": "<endpoint id 2>"
          }
      ],
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      }
    }
  }
}

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 users to find and monitor your devices.

Value Description
ACTIVITY_TRIGGER A 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 A device that cools the air in interior spaces.
AIR_FRESHENER A device that emits pleasant odors and masks unpleasant odors in interior spaces.
AIR_PURIFIER A device that improves the quality of air in interior spaces.
AUTO_ACCESSORY A smart device in an automobile, such as a dash camera.
BLUETOOTH_SPEAKER A speaker that connects to an audio source over Bluetooth.
CAMERA A security device with video or photo functionality.
CHRISTMAS_TREE A religious holiday decoration that often contains lights.
COFFEE_MAKER A device that makes coffee.
COMPUTER A non-mobile computer, such as a desktop computer.
CONTACT_SENSOR An endpoint that detects and reports changes in contact between two surfaces.
DISHWASHER A device that cleans dishes.
DOOR A door.
DOORBELL A doorbell.
DRYER A device that dries wet clothing.
EXTERIOR_BLIND A window covering, such as blinds or shades, on the outside of a structure.
FAN A fan.
GAME_CONSOLE A game console, such as Microsoft Xbox or Nintendo Switch
GARAGE_DOOR A garage door. Garage doors must implement the ModeController interface to open and close the door.
HEADPHONES A wearable device that transmits audio directly into the ear.
HUB A smart-home hub.
INTERIOR_BLIND A window covering, such as blinds or shades, on the inside of a structure.
LAPTOP A laptop or other mobile computer.
LIGHT A light source or fixture.
MICROWAVE A microwave oven.
MOBILE_PHONE A mobile phone.
MOTION_SENSOR An endpoint that detects and reports movement in an area.
MUSIC_SYSTEM A network-connected music system.
NETWORK_HARDWARE A network router.
OTHER An endpoint that doesn't belong to one of the other categories.
OVEN An oven cooking appliance.
PHONE A non-mobile phone, such as landline or an IP phone.
PRINTER A device that prints.
ROUTER A network router.
SCENE_TRIGGER A 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 A projector screen.
SECURITY_PANEL A security panel.
SECURITY_SYSTEM A security system.
SLOW_COOKER An electric cooking device that sits on a countertop, cooks at low temperatures, and is often shaped like a cooking pot.
SMARTLOCK An endpoint that locks.
SMARTPLUG A module plugged into an existing electrical outlet, and then has a device plugged into it. For example, a user 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 A speaker or speaker system.
STREAMING_DEVICE A streaming device, such as Apple TV, Chromecast, or Roku.
SWITCH A switch wired directly to the electrical system. A switch can control a variety of devices.
TABLET A tablet computer.
TEMPERATURE_SENSOR An 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 An 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 A television.
VACUUM_CLEANER A vacuum cleaner.
VEHICLE A motor vehicle (automobile, car).
WASHER A device that cleans clothing.
WATER_HEATER A device that heats water, often consisting of a large tank.
WEARABLE A network-connected wearable device, such as an Apple Watch, Fitbit, or Samsung Gear.