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.

Dependencies

The device implementing the Alexa.Discovery 3.0 capability must also implement support for

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:


Was this page helpful?

Last updated: Nov 27, 2023