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.

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

Important: The 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
`event`	Defines header and endpoint information.	`Event` object	Yes
`event.header`	Identifies the event and namespace.	`Header` object	Yes
`event.header.namespace`	Identifies the interface of the message payload. Valid value: `Alexa.Discovery`.	String	Yes
`event.header.name`	Name of the event. Valid value: `AddOrUpdateReport`.	String	Yes
`event.header.messageId`	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. Use for tracking purposes. You can log the message ID, but don't use the message ID to program business logic. Valid value: String of alphanumeric characters and dashes up to 128 characters.	String	Yes
`event.header.eventCorrelationToken`	Universally unique identifier (UUID) generated to the RFC 4122 specification that AVS will return in the subsequent `EventProcessed` directive.	String	Yes
`event.payload`	Identifies the properties that changed. If the message doesn't include a payload, set to an empty object.	Payload object	Yes
`event.payload.scope`	Token acquired during authorization and which is also provided in the header of HTTP/2 messages.	Scope object	Yes
`event.payload.endpoints`	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 `Endpoint` objects	No
`event.payload.endpoints[].endpointId`	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`: Client ID of the device maintaining the HTTP/2 connection, generated during product registration. This ID must match the `client_id` or `clientId` fields used to acquire access tokens during the device's authorization flow. `productId`: 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`: 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	Yes
`event.payload.endpoints[].registration`	Device registration information. Included only when the endpoint is the device maintaining the HTTP/2 connection, reporting itself.	Registration object	No
`event.payload.endpoints[].manufacturerName`	Name of the manufacturer of the device. Valid value: Up to 128 characters.	String	Yes
`event.payload.endpoints[].description`	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." Valid value: Up to 128 characters.	String	Yes
`event.payload.endpoints[].friendlyName`	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. Valid value: Up to 128 alphanumeric characters and spaces. Don't include special characters or punctuation.	String	Yes
`event.payload.endpoints[].displayCategories`	Category under which your device displays in the Alexa app.	Array of strings from display categories	Yes
`event.payload.endpoints[].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.	`AdditionalAttributes` object	Recommended
`event.payload.endpoints[].capabilities`	Capability interfaces that represent capabilities implemented by the device on behalf of the endpoint, as defined by individual capability interfaces. Note: The device that maintains the HTTP/2 connection can implement all capabilities. Connected endpoints can assert Alexa, Alexa.ModeController, Alexa.RangeController, Alexa.ToggleController, and Alexa.PowerController only. The `capabilities` field is subject to size limits.	Array of `Capability` objects	Yes
`event.payload.endpoints[].connections`	Information about the methods that the device uses to connect to the internet and smart home hubs.	Array of `Connection` objects	No
`event.payload.endpoints[].relationships`	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.	`Relationships` object	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