Vielen Dank für Ihren Besuch. Diese Seite ist momentan nur auf Englisch verfügbar. Wir arbeiten an der deutschen Version. Vielen Dank für Ihr Verständnis.

Alexa.Discovery

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.

Directives

Discovery is supported in all of the supported smart home skill languages. For more information on language support, see Develop Smart Home Skills in Multiple Languages.

Discover

Request to discover endpoints associated with the customer's device or service account. If there are no endpoints to discover, the customer's access token has expired, or if an error associated with the customer's account occurs, the skill should return an empty endpoints array in the Discover.Response, and not an error message.

User: Alexa, discover my smart home devices

User: Alexa, finde meine smarten geräte

Example: Discover directive

{
  "directive": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456"
    },
    "payload": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      }
    }
  }
}

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. There are two different kind of scope types that could be present in a discovery request:

  • BearerToken - Provides an OAuth bearer token for accessing a linked customer account or identifying an Alexa customer. Typically used for Smart Home Skills or Video Skills.

  • BearerTokenWithPartition - Provides an OAuth bearer token for accessing a linked customer account and the physical location (partition) where the discovery request should be applied. Typically used for skills that target Alexa for Business.

Events and Properties

For this interface, you can send:

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 the response you provide details about each endpoint such as:

  • A unique identifier
  • Display category for each endpoint
  • The customer name for the device
  • The properties of each endpoint that are retrievable and report changes in state.

If there are no devices to discover or if your device cloud encounters an error, return an empty endpoints array.

A capability can optionally define a configuration object, depending on the device category. The configuration object contains additional descriptive details about the endpoint. Check each capability topic for details about whether you can include a configuration object, and what that object should contain.

Example: Discover.Response

See Payload object descriptions for descriptions of objects in the Response message.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "appliance-001",
          "friendlyName": "Living Room Light",
          "description": "Smart Light by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "LIGHT"
          ],
          "cookie": {
            "extraDetail1": "optionalDetailToReferenceThisDevice",
            "extraDetail2": "There can be multiple entries",
            "extraDetail3": "Use for reference purposes",
            "extraDetail4": "Not a suitable place to maintain 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",
              "version": "3"
            },
            {
              "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
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                  "supported": [
                      {
                          "name": "connectivity"
                      }
                  ],
                  "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
            }
          ]
        },
        {
          "endpointId": "appliance-005",
          "friendlyName": "Watch TV",
          "description": "Smart Activity by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "ACTIVITY_TRIGGER"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.SceneController",
              "version": "3",
              "supportsDeactivation": 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",
              "version": "3"
            },
            {
              "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
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                  "supported": [
                      {
                          "name": "connectivity"
                      }
                  ],
                  "proactivelyReported": true,
                  "retrievable": true
              }
            }
          ]
        }
      ]
    }
  }
}

AddOrUpdateReport

Send this message proactively when a customer adds a new endpoint to their account or makes changes to an existing endpoint, such as renaming a scene. In this message, you provide details about each endpoint such as a unique identifier, the customer (friendly) name for the endpoint, capabilities the endpoint supports, and what properties of each capability are retrievable and proactively reported.

A capability can optionally contain a configuration object, depending on the device category. The configuration object contains additional descriptive details about the endpoint. Check each capability topic for details about whether you can include a configuration object, and what that object should contain.

An AddOrUpdateReport is very similar to a discovery response, however:

  • The name of the message is set to AddOrUpdateReport
  • The message includes a scope, which in turn includes a bearer token to identify the customer to Alexa, and an HTTP Authorization header that contains the same bearer token
  • The message is sent to the Alexa event gateway
  • This message can include all of the endpoints associated with the customer account, or only the new or updated endpoints. You can choose based on your skill implementation.

Example: Discover.AddOrUpdateReport

The following example shows an AddOrUpdateReport that describes a light. See Payload object descriptions for descriptions of objects in the Response message.


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": "appliance-001",
        "friendlyName": "Living Room Light",
        "description": "Smart Light by Sample Manufacturer",
        "manufacturerName": "Sample Manufacturer",
        "displayCategories": [
          "LIGHT"
        ],
        "cookie": {
          "extraDetail1": "optionalDetailForSkillToReferenceThisDevice",
          "extraDetail2": "There can be multiple entries",
          "extraDetail3": "use for reference purposes",
          "extraDetail4": "Do not use to maintain 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
            }
          }
        ]
      }],
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      }
    }
  }
}

Payload details

The payload of a Discovery.Response or an AddOrUpdateReport contains a scope to identify the user to Alexa, and an array of endpoints. Each endpoint describes one of the following:

  • Physical device
  • Virtual device
  • Group or cluster of devices
  • Software component

The following sections describe the objects in the payload.

Field Description Type Required
endpoints An array of endpoint objects that represents the devices/components associated with a customer’s device cloud account. If there are no devices associated with the customer account or an error occurs, this property should contain an empty array. The maximum number of items allowed in the array is 300. object array Yes
scope An object containing a bearer token to identify the customer to Alexa. scope object Required for AddOrUpdateReport events.
endpoint object

Represents a connected device/component 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 letters or numbers, spaces, and the following special characters: _ - = # ; : ? @ &. The identifier cannot exceed 256 characters. string that contains letters or numbers, spaces or 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 how the device should display in the Alexa app. The specified category determines the icon and device details displayed 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 Netflix" 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.  
MICROWAVE Indicates a microwave oven endpoint.  
OTHER An endpoint that cannot be described in one 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.
SPEAKER 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. The endpoint's temperature data is not shown in the Alexa app.
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>". Array of name/value pairs No
proactivelyReported Indicates whether the properties listed for this endpoint generate ChangeReport events. 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. boolean No
retrievable Indicates whether the properties listed for this endpoint can be retrieved for state reporting. 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. boolean No

capability versions

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

DeleteReport

Send this message proactively when a customer removes an endpoint from their account.

Example: DeleteReport


POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json

{
  "event": {
    "header": {
      "messageId": "0a29824b-9299-4d55-b0c3-1d96ecfae81e",
      "name": "DeleteReport",
      "namespace": "Alexa.Discovery",
      "payloadVersion": "3"
    },
    "payload": {
      "endpoints": [{
          "endpointId": "videoDevice-001"
        },
        {
          "endpointId": "speaker-001"
        }
      ],
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      }
    }
  }
}

Payload details

The payload of a delete report is described in the following table.

Field Description Type Required
endpoints Endpoints to delete from the customer account. A list of endpointIds that identifies the endpoints to delete. Yes
scope An object containing a bearer token to identify the customer to Alexa. scope object Yes

More Examples

Discover.Response example for an entertainment device

{
   "event":{
      "header":{
         "namespace":"Alexa.Discovery",
         "name":"Discover.Response",
         "payloadVersion":"3",
         "messageId":"abc-123-def-456"
      },
      "payload":{
         "endpoints":[
            {
               "endpointId":"appliance-001",
               "friendlyName":"Living Room Sound System",
               "description":"Smart Speaker by Sample Manufacturer",
               "manufacturerName":"Sample Manufacturer",
               "displayCategories": ["SPEAKER"],
               "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":"3",
                     "properties":{
                        "supported":[
                           {
                              "name":"volume"
                           },
                           {
                              "name":"muted"
                           }
                        ]
                     }
                  },
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.StepSpeaker",
                     "version":"3",
                     "properties":{

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

Discover.Response example for a video skill

{
 "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "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": "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"
          }

        ],
        "endpointId": "videoDevice-001",
        "description": "Device description for the customer",
        "displayCategories": ["OTHER"],
        "friendlyName": "Upstairs Amazon Player",
        "manufacturerName": "Amazon",
        "cookie": {}
      }]
    }
  }
}
Topic Description
Smart Home Skill API Message Reference Provides descriptions of directive and events, and their contents.
How to Proactively Manage Endpoints Describes how to use the AddOrUpdateReport or DeleteReport messages.