Alexa.Discovery Interface

Note: Sign in to the developer console to build or publish your skill.

Note: On December 31, 2021, we paused support for third-party device makers working with Alexa Gadgets, while we work to create an even better developer and customer experience. Please stay tuned to the Amazon developer portal for updates. In the interim, please visit the landing pages for Alexa Voice Service, Alexa Connect Kit, and Alexa Skills Kit to discover ways you can provide new customer experiences with voice.

This interface enables the Echo device to discover the following information about a gadget:

the details of the gadget, such as its type, manufacturer, firmware version, and so on
the capabilities, or interfaces, that the gadget supports

The Echo device gets this information from the gadget when they connect or reconnect over Bluetooth. To request the information, the Echo device sends the gadget a Discover directive. The gadget responds with a Discover.Response event that contains all the information.

Note: Each directive and event is a compilation of three separate .proto files: a header, a payload, and a file that combines the two. You can download the .proto files from the Alexa Gadgets Sample Code GitHub repository. In this topic, the .proto files combine all fields into one file for descriptive purposes.

Directives
- Discover directive
Events
- Discover.Response event

Directives

This interface includes one directive: Discover, as described next.

Discover directive

This directive queries the gadget for its details and capabilities. The .proto file contents are as follows:

syntax = "proto3";

message DiscoverDirectiveProto {
   Directive directive = 1;
   message Directive {
      alexaDiscovery.DiscoverDirectivePayloadProto payload = 2;
      header.DirectiveHeaderProto header = 1;
   }
}

message DirectiveHeaderProto {
   string namespace = 1;
   string name = 2;
   string messageId = 3;
   string dialogRequestId = 4;      
}

message DiscoverDirectivePayloadProto {
   Scope scope = 1;
   message Scope {
      string type = 1; 
      string token = 2; 
   }
}

DiscoverDirectiveProto

The fields in this message are as follows:

Field	Description	Type
`directive`	Contains a complete `Discover` directive.	`Directive`

Directive

The fields of the message are as follows:

Field	Description	Type
`header`	Contains the header for this directive.	`DirectiveHeaderProto`
`payload`	Contains the payload for this directive.	`DiscoverDirectivePayloadProto`

DirectiveHeaderProto

The fields of the message are as follows:

Field	Description	Type
`namespace`	The namespace of this directive, which is `Alexa.Discovery`.	`string`
`name`	The name of this directive, which is `Discover`.	`string`
`messageId`	An ID that uniquely defines an instance of this directive. This string can be empty.	`string`
`dialogRequestId`	A unique ID that correlates this directive with a specific voice interaction from a user. You can ignore this field.	`string`

DiscoverDirectivePayloadProto

The fields of the message are as follows:

Field	Description	Type
`scope`	You can ignore this message.	`Scope`

Scope

The fields of the message are as follows:

Field	Description	Type
`type`	Empty string.	`string`
`token`	Empty string.	`string`

Events

This interface includes one event: Discover.Response, as described next.

Discover.Response event

This gadget uses this event to report its details and capabilities. The .proto file contents are as follows:

syntax = "proto3";

message DiscoverResponseEventProto {
   Event event = 1;
   message Event {
      alexaDiscovery.DiscoverResponseEventPayloadProto payload = 2;
      header.EventHeaderProto header = 1;
   }
}

message EventHeaderProto {
   string namespace = 1; 
   string name = 2; 
   string messageId = 3; 
}

message DiscoverResponseEventPayloadProto {
   repeated Endpoints endpoints = 1;
   message Endpoints {
      repeated Capabilities capabilities = 11;
      message Capabilities {
         Configuration configuration = 4;
         message Configuration {
            repeated SupportedTypes supportedTypes = 1;
            message SupportedTypes {
               string name = 1;
            }
         }
         string type = 1;
         string interface = 2;
         string version = 3;
      }
      AdditionalIdentification additionalIdentification = 12;
      message AdditionalIdentification {
         string modelName = 5;
         string deviceTokenEncryptionType = 3;
         string firmwareVersion = 1;
         string amazonDeviceType = 4;
         string radioAddress = 6;
         string deviceToken = 2;
      }
      string endpointId = 1;
      string manufacturerName = 4;
      string description = 3;
      string friendlyName = 2;
   }
}

DiscoverResponseEventProto

The fields in this message are as follows:

Field	Description	Type	Required
`event`	Contains a complete `Discover.Response` event.	`Event`	Yes

Event

The fields of the message are as follows:

Field	Description	Type	Required
`header`	Contains the header for this event.	`EventHeaderProto`	Yes
`payload`	Contains the payload for this event.	`DiscoverResponseEventPayloadProto`	Yes

EventHeaderProto

The fields of the message are as follows:

Field	Description	Type	Required
`namespace`	The namespace of this event, which is `Alexa.Discovery`.	`string`	Yes
`name`	The name of this event, which is `Discover.Response`.	`string`	Yes
`messageId`	An ID that uniquely defines an instance of this directive. This string can be empty.	`string`	Yes

DiscoverResponseEventPayloadProto

The fields of the message are as follows:

Field	Description	Type	Required
`endpoints`	An array of endpoints. Each endpoint represents a gadget that is connected to the Echo device.	Array of `Endpoints`	Yes

Endpoints

The fields of the message are as follows:

Field	Description	Type	Required
`capabilities`	An array of capabilities of the gadget. Capabilities represent the interfaces that a gadget supports.	Array of `Capabilities`	Yes
`AdditionalIdentification`	Additional information about the gadget, such as model name, firmware version, and so on.	`AdditionalIdentification`	Yes
`endpointId`	A gadget identifier. This identifier must meet the requirements in Gadget ID Requirements for Alexa Gadgets.	`string`	Yes
`manufacturerName`	The name of the device manufacturer. This value cannot exceed 128 characters. Example: `"AMAZON"`.	`string`	Yes
`description`	A human-readable description of the gadget. This value cannot exceed 128 characters. Example: `"EchoButtons"`.	`string`	Yes
`friendlyName`	The name that the user uses to identify the gadget. This name must match the friendly name of the Bluetooth device. For BR/EDR-based gadgets, the `friendlyName` is a part of the Extended Inquiry Response (EIR). For BLE gadgets, the `friendlyName` is either input using advertisement data, scan response data, or the GAP profile as described in Assigned numbers and GAP in the Bluetooth specification. This value can't exceed 15 characters and shouldn't contain special characters or punctuation. Example: `EchoButton1`.	`string`	Yes

Capabilities

The gadget must include a Capabilities object for every interface that it supports. To find out what to put here, see the Supporting this Interface section of the interface's API reference. As one example, see the API reference for Notifications.

The Capabilities fields are as follows:

Field	Description	Type	Required
`type`	Indicates the type of capability, which determines what fields the capability has. Currently, `AlexaInterface` is the only valid value.	`string`	Yes
`interface`	The qualified name of the interface that describes the actions for the gadget.	`string`	Yes
`version`	Indicates the interface version that this gadget supports.	`string`	Yes
`configuration`	Contains additional descriptive details about the gadget.	`Configuration`	No

Configuration

The fields are as follows:

Field	Description	Type	Required
`supportedTypes`	The types, within the capability, that the gadget supports.	`SupportedTypes`	Yes

SupportedTypes

The fields are as follows:

Field	Description	Type	Required
`name`	A type, within the capability, that the gadget supports. You only need to provide this when the capability supports multiple types. For example, if a gadget supports the `Alexa.Gadget.StateListener` interface, see Supporting This Interface in that topic to learn that `name` can be `alarms`, `timers`, `reminders`, and so on.	`string`	Yes

AdditionalIdentification

The fields are as follows:

Field	Description	Type	Required
`modelName`	A general name for the type of gadget. Example: `"EchoButton"`.	`string`	Yes
`deviceTokenEncryptionType`	The device secret algorithm. The only valid value is currently `1`, which means that the algorithm is SHA256.	`string`	Yes
`firmwareVersion`	The version of the firmware that is running on the gadget, which is used to determine whether the gadget needs an over-the-air (OTA) update.	`string` that contains an integer	Yes
`amazonDeviceType`	The type of gadget. This is the Amazon ID that is displayed on the gadget's product page in the developer portal.	`string`	Yes
`radioAddress`	The MAC address of the gadget, in hexadecimal format. Example: `"0123456789AB"`	`string`	Yes
`deviceToken`	A UTF-8-encoded string that contains the `SHA256` of the following: the `endpointId` concatenated with the Alexa Gadget Secret that is shown in the developer portal after you register your gadget. The following code shows how to calculate the device token in Python: `import hashlib def generate_token(device_id, device_token): hash_object = ( hashlib.sha256(bytes(device_id, 'utf-8') + bytes(device_token, 'utf-8')) ) hex_dig = hash_object.hexdigest() return bytes(hex_dig, 'utf-8')`	`string`	Yes

Last updated: Mar 31, 2022