Alexa.Discovery 3.0
The Alexa.Discovery capability interface comprises the mechanics related to informing Alexa about the device and its connected endpoints, including support for other capabilities, connection information, and other metadata.
The device that maintains the HTTP/2 connection to the Alexa Voice Service implements this interface on its own behalf only. Unlike other capability interfaces, Alexa.Discovery is never implemented on behalf of any connected endpoints.
(1) to implement support for connected endpoints;
(2) to support Alexa 3.0, Alexa.ModeController 3.0, Alexa.RangeController 3.0, Alexa.ToggleController 3.0, or Alexa.PowerController 3.0 on either the device or any connected endpoints.
Discover
directive or Discover.Response
event.Dependencies
The device implementing the Alexa.Discovery 3.0 capability must also implement support for
- Alexa.ApiGateway 1.0 or higher,
- InteractionModel 1.2 or higher, and
- if the device has an onboard microphone, SpeechRecognizer 2.3 or higher
Capability assertion
Unlike other capability interfaces, support for Alexa.Discovery 3.0 is implicit. The device must not report support for Alexa.Discovery 3.0 within its own capability assertion payload.
Events
AddOrUpdateReport
The AddOrUpdateReport
event allows the device to proactively send Alexa information about itself and any connected endpoints.
The event's contents are additive on a per-endpoint basis. Every time the device sends this event, Alexa discards the contents (from previously sent AddOrUpdateReport
events) for individually included endpoints and replaces them with the newly provided endpoint object. Alexa will remember the details of endpoints that the device previously included, but omitted in a followup AddOrUpdateReport
report. To delete an endpoint, the device must send the DeleteReport
event.
Use the following guidance to determine when the device must send the AddOrUpdateReport
event:
- On device boot, the device must send the event*, only if
- the device is booting up for the first time (OOBE);
- the device is unable to persist information about connected endpoints, capabilities, and metadata across reboots; or
- the device just completed a firmware update.
- During runtime, the device must send the event
- whenever the device acquires a new access token due to an association with a new or different Amazon customer account*;
- whenever the device detects added endpoints;
- whenever the device or its connected endpoints support new or changed capabilities or have support removed; and
- whenever other device or endpoint metadata changes.
* In these cases, the device must send the AddOrUpdateReport
event only after first sending the VerifyGateway
event and either receiving an empty HTTP 204
response or processing the SetGateway
directive.
AVS responds with an EventProcessed
directive after processing the event.
- As the user completes the initial Out of Box Experience (OOBE) for setup, the device shouldn't send any other events on behalf of any endpoints until the device receives the
EventProcessed
directive. - If a user adds or updates an endpoint, the device can send other events on behalf of any endpoint until receiving the
EventProcessed
directive.
Sample Message
{ "event": { "header": { "namespace": "Alexa.Discovery", "name": "AddOrUpdateReport", "payloadVersion": "3", "messageId": "{{STRING}}", "eventCorrelationToken": "{{STRING}}" }, "payload": { "scope": { "type": "BearerToken", "token": "{{STRING}}" }, "endpoints": [ { "endpointId": "{{STRING}}", "registration": { "productId": "{{STRING}}", "deviceSerialNumber": "{{STRING}}" }, "manufacturerName": "{{STRING}}", "description": "{{STRING}}", "friendlyName": "{{STRING}}", "displayCategories": ["{{STRING}}", ...], "additionalAttributes": { "manufacturer": "{{STRING}}", "model": "{{STRING}}", "serialNumber": "{{STRING}}", "firmwareVersion": "{{STRING}}", "softwareVersion": "{{STRING}}", "customIdentifier": "{{STRING}}" }, "capabilities": [ // list of capability assertion objects, representing capabilities // implemented by the device on behalf of the endpoint, // as defined by individual capability interfaces ], "connections": [ { "type": "{{STRING}}", "macAddress": "{{STRING}}", "homeId": "{{STRING}}", "nodeId": "{{STRING}}", "value": "{{STRING}}" }, ... ] }, ... ] } } }
Message Parameters
Parameter | Description | Type |
---|---|---|
event. header. messageId |
A universally unique identifier (UUID) generated to the RFC 4122 specification. | string |
event. header. eventCorrelationToken |
A universally unique identifier (UUID) generated to the RFC 4122 specification that AVS will return in the subsequent EventProcessed directive. |
string |
event. payload. scope. token |
The LWA token acquired during authorization and which is also provided in the header of HTTP/2 messages. | string |
event. payload. endpoints |
The list of endpoints for which this device implements capabilities, including the device itself. The device maintains the connection to Alexa on behalf of the listed endpoints. | list |
event. payload. endpoints[i]. endpointId |
The unique identifier of the endpoint, using the following format: <clientId>::<productId>::<serialNumber>[-<extEndpoint>] . An identifier can contain letters or numbers, spaces, and the following special characters: _ - = # ; : ? @ & . The identifier can't exceed 256 characters. Note: Existing AVS devices with serial numbers, client IDs, or product IDs that contain invalid characters can't support Smart Home without a firmware update and requiring the user to re-register the device. clientId : The client ID of the device maintaining the HTTP/2 connection, generated during product registration. This must match the client_id or clientId fields used to acquire access tokens during the device's authorization flow.productId : The product ID of the device maintaining the HTTP/2 connection. This must match the registration.productId field value for the endpoint object representing the device.serialNumber : The serial number of the device maintaining the HTTP/2 connection. This must match the registration.deviceSerialNumber field value for the endpoint object representing the device.extEndpoint : If the endpointId is of a connected endpoint, rather than the device itself, the device assigns an identifier for it using [a-zA-Z0-9_-=#;:?@& ] . The identifier must be unique across endpoints connected to the device. |
string |
event. payload. endpoints[i]. registration |
This object must be included only when the endpoint is the device maintaining the HTTP/2 connection, reporting itself. | object |
event. payload. endpoints[i]. registration. productId |
This is the developer-provided product ID created during product registration. It must match the productId or PRODUCT_ID fields used to acquire access tokens during the device's authorization flow.
|
string |
event. payload. endpoints[i]. registration. deviceSerialNumber |
This is the device-generated serial number that's unique among all devices sharing the same productId . It must match the deviceSerialNumber or PRODUCT_DSN fields used to acquire access tokens during the device's authorization flow.
|
string |
event. payload. endpoints[i]. manufacturerName |
The name of the manufacturer of the device. This value can contain up to 128 characters. | string |
event. payload. endpoints[i]. description |
The description of the device. The description should contain the manufacturer name or how the device connects. For example, "Smart Lock by Sample Manufacturer" or "Bluetooth Temperature Sensor connected via AVS Thermostat." This field can contain up to 128 characters. | string |
event. payload. endpoints[i]. friendlyName |
The name used by the user to identify the device. You set an initial value, and later the user can change the friendly name by using the Alexa app. This field can contain up to 128 characters, and shouldn't contain special characters or punctuation. This field is required for all interfaces, with some exceptions. Check the documentation for your interface to see if this field is optional. | string |
event. payload. endpoints[i]. displayCategories[j] |
The category that the endpoint will be displayed under in the Alexa app. For accepted values, see display categories. |
string |
event. payload. endpoints[i]. additionalAttributes |
Additional information about the endpoint. Amazon recommends that you include this field because it can improve the user experience in the Alexa app. When different skills describe the same device in different ways, the same device appears multiple times in the Alexa app, which confuses users. Alexa can use the additionalAttributes object to identify duplicate devices and improve the user experience in the Alexa app. |
string |
event. payload. endpoints[i]. additionalAttributes. manufacturer |
The name of the manufacturer of the device. This must match the manufacturerName field. This value can contain up to 256 alphanumeric characters, and can contain punctuation.
|
string |
event. payload. endpoints[i]. additionalAttributes. model |
The name of the model of the device as advertised to customers. The model should uniquely identify the specific variant of a product. For example, for the vehicle Audi A6 2020, the manufacturer would be Audi and the model would be A6 2020. This field can contain up to 256 alphanumeric characters, and can contain punctuation. |
string |
event. payload. endpoints[i]. additionalAttributes. serialNumber |
The serial number of the endpoint. This may be any manufacturer-specific identifier of the endpoint. It must be unique among other endpoints sharing the same manufacturer and model . This field can contain up to 256 alphanumeric characters, and can contain punctuation. If this the endpoint is the device maintaining the HTTP/2 connection reporting itself, this must match the registration.deviceSerialNumber field.
|
string |
event. payload. endpoints[i]. additionalAttributes. firmwareVersion |
The manufacturer-provided firmware version of the endpoint. This field can contain up to 256 alphanumeric characters, and can contain punctuation. |
string |
event. payload. endpoints[i]. additionalAttributes. softwareVersion |
The manufacturer-provided software version of the endpoint component responsible for coordinating with the device on endpoint capabilities and metadata. This field can contain up to 256 alphanumeric characters, and can contain punctuation. |
string |
event. payload. endpoints[i]. additionalAttributes. customIdentifier |
Your custom identifier for the device. This identifier should be globally unique across different user accounts. This value can contain up to 256 alphanumeric characters, and can contain punctuation. Amazon recommends that you include this field because it can improve the user experience in the Alexa app. |
string |
event. payload. endpoints[i]. capabilities |
A list of capability assertion objects, representing capabilities implemented by the device on behalf of the endpoint, as defined by individual capability interfaces. Note: All capabilities may be implemented by the device maintaining the HTTP/2 connection. For connected endpoints, only Alexa, Alexa.ModeController, Alexa.RangeController, Alexa.ToggleController, and Alexa.PowerController may be asserted. |
string |
event. payload. endpoints[i]. connections |
An optional list of information about the connection methods or protocols the endpoint uses to connect to the internet or to the device. Note: The device sending this event should include only one TCP_IP object in this list for the endpoint object representing itself, because it maintains the HTTP/2 connection with Alexa.
|
string |
event. payload. endpoints[i]. connections[k]. type |
The connection type. Accepted Values: TCP_IP : The endpoint has its own internet connection. The macAddress field becomes required.ZIGBEE : The endpoint communicates with the device over Zigbee. The macAddress field becomes required.ZWAVE : The endpoint communicates with the device over Z-Wave. The homeId and nodeId fields become required.UNKNOWN : The endpoint uses some other protocol to connect to the device. The value field becomes required.
|
string |
event. payload. endpoints[i]. connections[k]. macAddress |
The unique identifier of the network interface controller if type is TCP_IP or ZIGBEE .
|
string |
event. payload. endpoints[i]. connections[k]. homeId |
The Home ID of a Z-Wave network the endpoint connects to in 0x00000000 UTF-8 format if type is ZWAVE .
|
string |
event. payload. endpoints[i]. connections[k]. nodeId |
The Node ID of the endpoint on a Z-Wave network in 0x00 UTF-8 format if type is ZWAVE .
|
string |
event. payload. endpoints[i]. connections[k]. value |
The connection information when type is UNKNOWN . The value should stable, specific, and uniquely identifying. It may contain up to 256 alphanumeric characters and punctuation.
|
string |
DeleteReport
The DeleteReport
event allows the device to proactively report any endpoints that the user has disconnected from the device and the user's account.
The device must send the DeleteReport
event instead of sending the AddOrUpdateReport
event with the deleted endpoints omitted.
Sample Message
{ "event": { "header": { "namespace": "Alexa.Discovery", "name": "DeleteReport", "payloadVersion": "3", "messageId": "{{STRING}}" }, "payload": { "scope": { "type": "BearerToken", "token": "{{STRING}}" }, "endpoints": [ { "endpointId": "{{STRING}}" }, ... ] } } }
Message Parameters
Parameter | Description | Type |
---|---|---|
event. header. messageId |
A universally unique identifier (UUID) generated to the RFC 4122 specification. | string |
event. payload. scope. token |
The LWA token acquired during authorization and which is also provided in the header of HTTP/2 messages. | string |
event. payload. endpoints[i]. endpointId |
The identifier of the deleted endpoint, previously reported to Alexa in the AddOrUpdateReport event.Note: This may not be the endpointId of the device sending the event.
|
string |
Additional resources
The Alexa.Discovery 3.0 capability has its origins in the Alexa Skills Kit. It is now available directly to AVS devices with an HTTP/2 connection, without requiring an AWS Lambda or maintaining a separate cloud service. The following resources provide additional context and examples: