Thank you for your visit. This page is only available in English at this time.

Alexa.Discovery Interface

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 a customer 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 customer account.

Properties and Objects

The endpoint object

The endpoint object represents a connected device or component associated with a customer's device cloud account. An endpoint describes one of the following:

  • A physical device
  • A virtual device
  • A group or cluster of devices
  • A software component

Endpoint object example

{
  "endpointId": "<unique ID of the endpoint>",
  "manufacturerName": "Sample Manufacturer",
  "description": "Smart Light by Sample Manufacturer",
  "friendlyName": "Living Room Light",
  "additionalAttributes":  {
  },
  "displayCategories": [
    "LIGHT"
  ],
  "capabilities": [
  ],
  "connections": [
  ],
  "cookie": {
    "extraDetail1": "information used by your skill",
    "extraDetail2": "you can have multiple entries",
    "extraDetail3": "do not store device state here"
  }
}

Endpoint object schema

Field Description Type Required
endpointId The identifier for the endpoint. The identifier must be unique across all devices for the skill. In addition, the identifier must be consistent for all discovery requests for the same device. An identifier can contain letters or numbers, spaces, and the following special characters: _ - = # ; : ? @ &. The identifier cannot exceed 256 characters. String Yes
manufacturerName The name of the manufacturer of the device. This value can contain up to 128 characters. String Yes
description The description of the device. The description should contain the manufacturer name or how the device is connected. For example, "Smart Lock by Sample Manufacturer" or "WiFi Thermostat connected via SmartHub". This value can contain up to 128 characters. String Yes
friendlyName The name used by the customer to identify the device. This value can contain up to 128 characters, and should not contain special characters or punctuation. String Yes
additionalAttributes Additional information about the endpoint. An additionalAttributes object. No
displayCategories In the Alexa app, the category that your device is displayed in. An array of strings from display categories. Yes
capabilities The capability interfaces that your skill supports for the endpoint, such as Alexa.BrightnessController or Alexa.PowerController. An array of capability objects. Yes
connections Information about the methods that the device uses to connect to the internet and smart home hubs. An array of connection objects. No
cookie Information about the device that your skill uses. The contents of this property cannot exceed 5000 bytes. The API doesn't read or use this data. A list of name/value pairs. No

The additionalAttributes object

The additionalAttributes object contains additional information about an endpoint. Alexa can use this information to identify devices when different skills describe the same device in different ways.

Additional attributes object example

{
  "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>"
  }
}

Additional attributes object schema

Field Description Type Required
manufacturer The name of the manufacturer of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. String No
model The name of the model of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. String No
serialNumber The serial number of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. String No
firmwareVersion The firmware version of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. String No
softwareVersion The software version of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. String No
customIdentifier Your custom identifier for the device. This identifier should be globally unique in your systems across different customer accounts. This value can contain up to 256 alphanumeric characters, and can contain punctuation. String No

The capability object

A capability object represents an interface that your skill supports. For example, your skill might support turning on a light by supporting the Alexa.PowerController interface. To find available interfaces for smart home devices, see List of Capability Interfaces and Supported Locales.

Capability object example

{
    "type": "AlexaInterface",
    "interface": "Alexa.PercentageController",
    "version": "3",
    "properties": {
        "supported": [
            {
                "name": "percentage"
            }
        ],
        "proactivelyReported": true,
        "retrievable": true
    }
}

Capability object schema

Field Description Type Required
type The type of capability. Currently, the only available type is AlexaInterface. String Yes
interface The name of the capability interface. String Yes
version The version of the interface. Different interfaces have different versions from each other. Always check the documentation for an interface to verify the current version. String Yes
properties.supported The properties of the interface which are supported by your skill. An array of name/value pairs. No
proactivelyReported True if your skill sends change reports when the properties change. The default is false. Boolean No
retrievable True if you respond to state report requests and report the values of the properties. The default is false. Boolean No

The connections property

The connections property represents the methods that a device uses to connect to the internet and smart home hubs. The connections property contains an array of connection objects.

Connections property example

{
  "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"
    }
  ]
}

Connection object schema

Field Description Type Required
type The type of connection; one of TCP_IP, ZIGBEE, ZWAVE, or UNKNOWN. String Yes
macAddress The unique identifier for the network interface controller (NIC). Optionally include this field when the connection type is TCP_IP or ZIGBEE. String No
homeId The Home ID for a Z-Wave network that the endpoint connects to. The format is 0x00000000 with UTF-8 characters. Optionally include this field when the connection type is ZWAVE. String No
nodeId The Node ID for the endpoint in a Z-Wave network that the endpoint connects to. The format is 0x00 with UTF-8 characters. Optionally include this field when the connection type is ZWAVE. String No
value The connection information for a connection when you can't identify the type of the connection more specifically. The information that you provide in this field should be stable and specific. This value can contain up to 256 alphanumeric characters, and can contain punctuation. String Yes when type = UNKNOWN

Directives

Discover directive

Support the Discover directive so that customers 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 customer 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

{
  "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 of the devices associated with the end-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 customer account, return an empty array for this property. The maximum number of endpoints you can return is 300. An array of endpoint objects. Yes

Discover response event example

The following example shows a discover response for a device that is a light. To see example discover responses for other capabilities, see the documentation for each interface at List of Capability Interfaces and Supported Locales.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "appliance-001",
          "manufacturerName": "Sample Manufacturer",
          "description": "Smart Light by Sample Manufacturer",
          "friendlyName": "Living Room 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"
          ],
          "capabilities": [
              {
                "type": "AlexaInterface",
                "interface": "Alexa.BrightnessController",
                "version": "3",
                "properties": {
                  "supported": [
                    {
                      "name": "brightness"
                    }
                  ],
                  "proactivelyReported": true,
                  "retrievable": true
                }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ColorController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "color"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ColorTemperatureController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "colorTemperatureInKelvin"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            }
          ],
          "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"
            }
          ],
          "cookie": {
          }
        }
      ]
    }
  }
}

Discover response event example for a video device

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<the manufacturer name of the endpoint>",
          "description": "<a description that is shown in the Alexa app>",
          "friendlyName": "Upstairs Video Player",
          "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": [
            "OTHER"
          ],
          "capabilities": [
            {
              "interface": "Alexa.RemoteVideoPlayer",
              "type": "AlexaInterface",
              "version": "1.0"
            },
            {
              "interface": "Alexa.ChannelController",
              "type": "AlexaInterface",
              "version": "3"
            },
            {
              "interface": "Alexa.PlaybackController ",
              "type": "AlexaInterface",
              "version": "3",
              "supportedOperations": ["Play", "Pause", "Stop"]
            },
            {
              "interface": "Alexa.VideoRecorder",
              "type": "AlexaInterface",
              "version": "1.0"
            },
            {
              "interface": "Alexa.Launcher",
              "type": "AlexaInterface",
              "version": "1.0"
            }
          ],
          "connections": [
          ],
          "cookie": {
          }
        }
      ]
    }
  }
}

Discover response event example for an entertainment device

{
  "event":{
    "header":{
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload":{
      "endpoints":[
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<the manufacturer name of the endpoint>",
          "description": "Smart Speaker by Sample Manufacturer",
          "friendlyName": "Living Room Sound System",
          "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": [
            "SPEAKER"
          ],
          "capabilities":[
            {
              "type":"AlexaInterface",
              "interface":"Alexa.Speaker",
              "version":"3",
              "properties":{
                "supported":[
                  {
                    "name":"volume"
                  },
                  {
                    "name":"muted"
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            }
          ],
          "connections": [
          ],
          "cookie": {
          }
        }
      ]
    }
  }
}

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 message 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 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 customer account, return an empty array for this property. The maximum number of endpoints you can return is 300. An array of endpoint objects. Yes
scope An object containing a bearer token to identify the customer to Alexa. A scope object. Yes

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": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
    },
    "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"
          ],
          "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": [
          ],
          "cookie": {
          }
        }
      ],
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      }
    }
  }
}

DeleteReport event

You send a DeleteReport event proactively when a customer removes an endpoint from their account.

DeleteReport event payload details

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

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": "<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. This 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.
CAMERA A media device with video or photo functionality.
CONTACT_SENSOR An endpoint that detects and reports changes in contact between two surfaces.
DOOR A door.
DOORBELL A doorbell.
FAN A fan.
LIGHT A light source or fixture.
MICROWAVE A microwave oven.
MOTION_SENSOR An endpoint that detects and reports movement in an area.
OTHER An endpoint that can't be described by one of the other categories.
SCENE_TRIGGER A combination of devices set to a specific state. Use scene triggers for scenes when the order of the state change is not important. For example, for a scene named "bedtime" you might turn off the lights and lower the thermostat, in any order.
SECURITY_PANEL A security panel.
SMARTLOCK An endpoint that locks.
SMARTPLUG A module that is 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.
SWITCH A switch wired directly to the electrical system. A switch can control a variety of devices.
TEMPERATURE_SENSOR An endpoint that reports temperature, but does not control it. The temperature data of the endpoint is not shown in the Alexa app.
THERMOSTAT An endpoint that controls temperature, stand-alone air conditioners, or heaters with direct temperature control.
TV A television.