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.

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.

Retry Strategy and Rate Limiting

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

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

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:

• Alexa.Discovery 3
• Resources and Assets