Alexa.Discovery 3.0
The Alexa.Discovery
capability interface describes messages used to identify the 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.
Alexa.Discovery
replaces the Capabilities API for reporting support for capabilities. A device must transition to Alexa.Discovery
in the following cases:(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.
Alexa.Discovery
capability interface for AVS smart home devices differs from its Smart Home Skills Kit counterpart. AVS smart home devices don't need to implement support for the Smart Home Skills 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
- SpeechRecognizer 2.3 or higher, if the device has an onboard microphone.
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.
You can report relationships between connected endpoints by including the Relationships
object in your AddOrUpdateReport
report. Then, related devices display under a parent device in the Alexa app. For more details, see Identify relationships between endpoints.
AddOrUpdateReport example
{ "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}}" }, "relationships": { ... }, ... ] }, ... ] } } }
AddOrUpdateReport properties
Property | Description | Type | Required |
---|---|---|---|
|
Defines header and endpoint information. |
|
Yes |
|
Identifies the event and namespace. |
|
Yes |
|
Identifies the interface of the message payload. |
String |
Yes |
|
Name of the event. |
String |
Yes |
|
Unique identifier for the message. Include a new value in every response and event that your skill sends. Amazon recommends using a version 4 UUID. |
String |
Yes |
|
Universally unique identifier (UUID) generated to the RFC 4122 specification that AVS will return in the subsequent |
String |
Yes |
|
Identifies the properties that changed. |
Payload object |
Yes |
|
Token acquired during authorization and which is also provided in the header of HTTP/2 messages. |
Scope object |
Yes |
|
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. |
Array of |
No |
|
Unique identifier of the endpoint, using the following format:
|
String |
Yes |
|
Device registration information. Included only when the endpoint is the device maintaining the HTTP/2 connection, reporting itself. |
Registration object |
No |
|
Name of the manufacturer of the device. |
String |
Yes |
|
Description of the device. The description should contain the manufacturer name or how the device connects. For example, "Smart Lock by Sample Manufacturer" or "Wi-Fi Thermostat connected by SmartHub." |
String |
Yes |
|
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. All interfaces require this field, with some exceptions. To see if this field is optional, check the documentation for your interface. |
String |
Yes |
|
Category under which your device displays in the Alexa app. |
Array of strings from display categories |
Yes |
|
Additional information about the endpoint. |
|
Recommended |
|
Capability interfaces that represent capabilities implemented by the device on behalf of the endpoint, as defined by individual capability interfaces. |
Array of |
Yes |
|
Information about the methods that the device uses to connect to the internet and smart home hubs. |
Array of |
No |
|
Endpoints to which an endpoint connects. Use to link an Alexa-enabled device with smart home endpoints in the Alexa app. For example, an Alexa-enabled soundbar might control a TV. |
|
No |
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:
Last updated: Mar 16, 2023