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

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: