Alexa.Discovery

The Alexa.Discovery interface describes messages used to request and identify the devices associated with the customer’s device account. You must respond to discovery directives so that a customer can discover the devices and scenes associated with your smart home skill.

Directives

This control and query directives in this interface are supported in skills that target the following languages:

  • English (US)
  • English (UK)
  • English (India)
  • German

See Develop Smart Home Skills in Multiple Languages for more information.

Discover

Request to discover devices or scenes associated with the end-user’s device cloud account. If there are no devices to discover, the customer’s access token has expired, or if your device cloud encounters some other error, the skill should return an empty Discover.Response, and not an error message.

“Alexa, discover my smart home devices”

“Alexa, finde meine smarten geräte”

Discovery example

{
  "directive": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
    },
    "payload": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      }
    }
  }
}

Payload details

The payload for a discovery request contains one object, a scope object.

A scope is a polymorphic object that provides authorization and identifying info for a message. For a discovery request, the scope will contain a bearer token that identifies the user to their account with the device cloud your skill targets.

Events and Properties

For this interface, you can reply:

  • Synchronously, which means you send a Response to Alexa in from the Lambda function.

When you send a Response, you should include the state of reportable properties in the context of the message

Reportable Properties

None

Discover.Response

Returns all of the devices associated with the end-user’s device cloud account. The expected response for a Discover directive. In this response you provide details about each device such as a unique identifier, the customer name for the device and what properties of each device are retrievable and report their current state. If there are no devices to discover or if your device cloud encounters an error, return an empty endpoints array.

Discover.Response example:

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "appliance-001",
          "friendlyName": "Living Room Light",
          "description": "Smart Light by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "LIGHT"
          ],
          "cookie": {
            "extraDetail1": "optionalDetailForSkillAdapterToReferenceThisDevice",
            "extraDetail2": "There can be multiple entries",
            "extraDetail3": "but they should only be used for reference purposes",
            "extraDetail4": "This is not a suitable place to maintain current device state"
          },
          "capabilities": [
            {
              "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
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ColorController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "color"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "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
              }
            }
          ]
        },
        {
          "endpointId": "appliance-002",
          "friendlyName": "Hallway Thermostat",
          "description": "Smart Thermostat by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "THERMOSTAT"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ThermostatController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "lowerSetpoint"
                  },
                  {
                    "name": "targetSetpoint"
                  },
                  {
                    "name": "upperSetpoint"
                  },
                  {
                    "name": "thermostatMode"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.TemperatureSensor",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "temperature"
                  }
                ],
                "proactivelyReported": false,
                "retrievable": true
              }
            }
          ]
        },
        {
          "endpointId": "appliance-003",
          "friendlyName": "Front Door",
          "description": "Smart Lock by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "SMARTLOCK"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.LockController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "lockState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            }
          ]
        },
        {
          "endpointId": "appliance-004",
          "friendlyName": "Goodnight",
          "description": "Smart Scene by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "SCENE_TRIGGER"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.SceneController",
              "version": "3",
              "supportsDeactivation": false,
              "proactivelyReported": true
            }
          ]
        },
        {
          "endpointId": "appliance-005",
          "friendlyName": "Watch TV",
          "description": "Smart Activity by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "ACTIVITY_TRIGGER"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.SceneController",
              "version": "3",
              "supportsDeactivation": true,
              "proactivelyReported": true
            }
          ]
        },
        {
          "endpointId": "appliance-006",
          "friendlyName": "Back Door Camera",
          "description": "Smart Camera by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "CAMERA"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.CameraStreamController",
              "version": "3",
              "cameraStreamConfigurations": [
                {
                  "protocols": [
                    "RTSP"
                  ],
                  "resolutions": [
                    {
                      "width": 1920,
                      "height": 1080
                    },
                    {
                      "width": 1280,
                      "height": 720
                    }
                  ],
                  "authorizationTypes": [
                    "BASIC"
                  ],
                  "videoCodecs": [
                    "H264",
                    "MPEG2"
                  ],
                  "audioCodecs": [
                    "G711"
                  ]
                },
                {
                  "protocols": [
                    "RTSP"
                  ],
                  "resolutions": [
                    {
                      "width": 1920,
                      "height": 1080
                    },
                    {
                      "width": 1280,
                      "height": 720
                    }
                  ],
                  "authorizationTypes": [
                    "NONE"
                  ],
                  "videoCodecs": [
                    "H264"
                  ],
                  "audioCodecs": [
                    "AAC"
                  ]
                }
              ]
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            }
          ]
        }
      ]
    }
  }
}

Payload details

Field Description Type Required
endpoints An array of endpoint objects that represents the devices associated with a customer’s device cloud account. If there are no devices associated with the customer account, this property should contain an empty array. The property can be null if an error occurs. The maximum number of items allowed in the array is 300. object array Yes

endpoint object

Represents a connected device associated with the customer’s device cloud account.

Field Description Type Required
endpoint.endpointId A device identifier. The identifier must be unique across all devices owned by an end user within the domain for the skill. In addition, the identifier needs to be consistent across multiple discovery requests for the same device. An identifier can contain any letter or number and the following special characters: _ - = # ; : ? @ &. The identifier cannot exceed 256 characters. string that contains any letter or number and the following special characters: _ - = # ; : ? @ & Yes
endpoint.manufacturerName The name of the device manufacturer. This value cannot exceed 128 characters. string Yes
endpoint.friendlyName The name used by the customer to identify the device. This value cannot exceed 128 characters and should not contain special characters or punctuation. string Yes
endpoint.description A human-readable description of the device. This value cannot exceed 128 characters. 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 cannot exceed 128 characters. string Yes
endpoint.displayCategories Indicates the group name where the device should display in the Alexa app. See Display categories for supported values. string array Yes
endpoint.cookie String name/value pairs that provide additional information about a device for use by the skill. The contents of this property cannot exceed 5000 bytes. The API doesn't use or understand this data. Map of string/value pairs No
endpoint.capabilities An array of capability objects that represents actions particular device supports and can respond to. A capability object can contain different fields depending on the type. object array Yes

Display categories

Providing the correct value for display category means that your endpoints will display in the correct category in the Alexa app, with the correct iconography. This makes it easier for customers to find and monitor your devices.

Value Description Notes
ACTIVITY_TRIGGER Describes a combination of devices set to a specific state, when the state change must occur in a specific order. For example, a “watch Neflix” scene might require the: 1. TV to be powered on & 2. Input set to HDMI1. Applies to Scenes
CAMERA Indicates media devices with video or photo capabilities.  
DOOR Indicates a door.  
LIGHT Indicates light sources or fixtures.  
OTHER An endpoint that cannot be described in on of the other categories.  
SCENE_TRIGGER Describes a combination of devices set to a specific state, when the order of the state change is not important. For example a bedtime scene might include turning off lights and lowering the thermostat, but the order is unimportant. Applies to Scenes
SMARTLOCK Indicates an endpoint that locks.  
SMARTPLUG Indicates modules that are plugged into an existing electrical outlet. Can control a variety of devices.
SPEAKERS Indicates the endpoint is a speaker or speaker system.  
SWITCH Indicates in-wall switches wired to the electrical system. Can control a variety of devices.
TEMPERATURE_SENSOR Indicates endpoints that report the temperature only.  
THERMOSTAT Indicates endpoints that control temperature, stand-alone air conditioners, or heaters with direct temperature control.  
TV Indicates the endpoint is a television.  

capability object

A capability is a polymorphic type. Currently, AlexaInterface is the only supported type of capability.

AlexaInterface capability

Describes the actions an endpoint is capable of performing and the properties that can be retrieved and report change notifications.

Field Description Type Required
type Indicates the type of capability, which determines what fields the capability has. string “AlexaInterface” Yes
interface The qualified name of the interface that describes the actions for the device. string Yes
version Indicates the interface version that this endpoint supports. string Yes
properties.supported Indicates the properties of the interface which are supported by this endpoint in the format "name":"<propertyName>". If you do not specify a reportable property of the interface in this array, the default is to assume that proactivelyReported and retrievable for that property are false. Array of name/value pairs No
proactivelyReported Indicates whether the properties listed for this endpoint generate Change.Report events. boolean No
retrievable Indicates whether the properties listed for this endpoint can be retrieved for state reporting. boolean No
capability versions

Currently most capabilities are version 3. Entertainment device capabilities are 1.0. Keep in mind that capabilities can change versions independent of each other. Always check the interface topic when you implement an interface to find out what the current version is.

Additional Examples

Discover.Response example for an entertainment device

{
   "event":{
      "header":{
         "namespace":"Alexa.Discovery",
         "name":"Discover.Response",
         "payloadVersion":"3",
         "messageId":"5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
      },
      "payload":{
         "endpoints":[
            {
               "endpointId":"appliance-001",
               "friendlyName":"Living Room Sound System",
               "description":"Smart Speaker by Sample Manufacturer",
               "manufacturerName":"Sample Manufacturer",
               "displayCategories": ["SPEAKERS"],
               "cookie":{
                  "extraDetail1":"optionalDetailForSkillAdapterToReferenceThisDevice",
                  "extraDetail2":"There can be multiple entries",
                  "extraDetail3":"but they should only be used for reference purposes",
                  "extraDetail4":"This is not a suitable place to maintain current device state"
               },
               "capabilities":[
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.Speaker",
                     "version":"1.0",
                     "properties":{
                        "supported":[
                           {
                              "name":"volume"
                           },
                           {
                              "name":"muted"
                           }
                        ]
                     }
                  },
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.StepSpeaker",
                     "version":"1.0",
                     "properties":{

                     }
                  }
               ]
            }
         ]
      }
   }
}

Discover.Response example for a video skill

{
    "event": {
        "header": {
            "messageId": "0a29824b-9299-4d55-b0c3-1d96ecfae81e",
            "name": "Discover.Response",
            "namespace": "Alexa.Discovery",
            "payloadVersion": "3"
        },
        "payload": {
            "endpoints": [
                {
                    "capabilities": [
                        {
                            "interface": "Alexa.RemoteVideoPlayer",
                            "type": "AlexaInterface",
                            "version": "1.0"
                        },
                        {
                            "interface": "Alexa.ChannelController",
                            "type": "AlexaInterface",
                            "version": "1.0"
                        },
                        {
                            "interface": "Alexa.PlaybackController ",
                            "type": "AlexaInterface",
                            "version": "1.0"
                        }
                    ],
                    "endpointId": "videoDevice-001",
                    "description": "Device description for the customer",
                    "displayCategories": ["OTHER"],
                    "friendlyName": "Upstairs Amazon Player",
                    "manufacturerName": "Amazon",
                    "cookie": {}

                }
            ]
        }
    }
} 

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo:

Discovery