Home > Alexa > Alexa Skills Kit

Alexa.Discovery Interface

intro

The Alexa.Discovery interface describes messages used to request and identify the devices associated with the customer’s device account. You must use this interface so that a customer can discover their devices and scenes.

Directives

The following table shows the directive support depending on the type of skill you are implementing.

Directive Skill Type
Discover Smart Home, Video

Discover

Request to discover devices or scenes associated with the end-user’s cloud account. This message is sent when a user configures a skill which is associated with a device or set of devices. In addition, in some cases, a customer can ask to discover their devices. If there are no devices to discover or if an error occurs, you should return an empty Discover.Response, and not an error message.

“Alexa, discover my smart home devices”

Discover 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

Reportable Properties

None

Discover.Response Event

Returns all of the devices associated with the end-user’s 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 supported. If there are no devices to discover or if your device cloud encounters an error, return an empty endpoints array.

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 Light by Sample Manufacturer",
               "manufacturerName":"Sample Manufacturer",
               "displayCategories": [ ],
               "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": [],
                    "friendlyName": "Upstairs Amazon Player",
                    "manufacturerName": "Amazon",
                    "cookie": {}

                }
            ]
        }
    }
} 

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
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

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. Currently, this is an empty array. string array Yes
endpoint.cookie String name/value pairs that provide additional information about a device for use by the skill adapter. The contents of this property cannot exceed 5000 bytes. The API doesn’t use or understand this data. map of string key/value pairs No

capability object

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

AlexaInterface capability

Describes the actions a device is capable of performing and the properties that can be retrieved and will report change notifications.

Field Description Type Required
type Indicates the type of capability, which determines what fields the capability has. string “Alexa.Interface” Yes
interface The qualified name of the Alexa.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>". Array of name/value pairs No