Alexa.Discovery Interface

    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 will respond with a EventProcessed directive when the event has been successfully processed. The device should not send any other events on behalf of any endpoint until it receives 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>]

    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.

    Note: The total length of the endpointId may not exceed 256 characters.     		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 endpoint.

    Note: The length of this field may not exceed 128 characters.     		string
    event.
      payload.
        endpoints[i].
          description    		 A description of the endpoint and its manufacturer or how it connects. For example, "Smart Lock by Acme" or "Bluetooth Temperature Sensor connected via AVS Thermostat".

    Note: The length of this field may not exceed 128 characters.     		string
    event.
      payload.
        endpoints[i].
          friendlyName    		 The name used by the end user to identify the endpoint.

    Note: The length of this field may not exceed 128 characters and may not include special characters or punctuation.     		string
    event.
      payload.
        endpoints[i].
          displayCategories[j]    		 The category that the endpoint will be displayed under in the Alexa app.

    Accepted values are available in the display categories section of the Smart Home Skills Kit documentation for its implementation of Alexa.Discovery.

    		 string
    event.
      payload.
        endpoints[i].
          additionalAttributes    		 An optional object containing additional metadata that aids Alexa in identifying an endpoint uniquely when it is reported in different ways by multiple devices.

    Note: The length of each of the fields in this object may not exceed 256 characters and may contain only alphanumeric characters and punctuation.     		string
    event.
      payload.
        endpoints[i].
          additionalAttributes.
            manufacturer    		 The name of the manufacturer of the endpoint. This must match the manufacturerName field. string
    event.
      payload.
        endpoints[i].
          additionalAttributes.
            model    		 The name of the model of the endpoint. 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.

    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. 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. string
    event.
      payload.
        endpoints[i].
          additionalAttributes.
            customIdentifier    		 An identifier for the endpoint that is globally unique across all your systems across different user accounts. 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:

    Amazon Alexa
    Amazon Appstore
    Amazon Web Services
    Amazon Dash Replenishment