Alexa Discovery Objects

The Alexa.Discovery interface describes messages used to identify the endpoints associated with the user's device account. You send a Discover.Response event so that a user can discover the devices and scenes associated with your Smart Home skill. For details, see Alexa.Discovery.

The following are the objects that you send to Alexa in your discovery messages.

Endpoint object

The Endpoint object represents a connected device or component associated with a user's device cloud account. An endpoint describes one of the following:

  • A physical device
  • A virtual device
  • A group or cluster of devices, such as in a scene
  • A software component, such as a mobile app

Endpoint object example

Copied to clipboard.

{
  "endpointId": "unique ID of the endpoint",
  "manufacturerName": "Sample Manufacturer",
  "description": "Smart Light by Sample Manufacturer",
  "friendlyName": "Living Room Light",
  "displayCategories": ["LIGHT"],
  "additionalAttributes": {
      "manufacturer" : "Sample Manufacturer",
      "model" : "Sample model",
      "serialNumber": "the serial number of the device",
      "firmwareVersion" : "the firmware version of the device",
      "softwareVersion": "the software version of the device",
      "customIdentifier": "Your custom identifier for the device"
  },
  "capabilities": [],
  "connections": [],
  "relationships": {},
  "cookie": {
    "extraDetail1": "information used by your skill",
    "extraDetail2": "you can have multiple entries",
    "extraDetail3": "don't save device state here"
  }
}

Endpoint object details

Field Description Type Required
endpointId Identifier for the endpoint. The identifier must be unique across all devices for the skill. The identifier must be consistent for all discovery requests for the same device. An identifier can contain letters or numbers, spaces, and the following special characters: _ - = # ; : ? @ &. The identifier can't exceed 256 characters. String Yes
manufacturerName Name of the manufacturer of the device. This value can contain up to 128 characters. String Yes
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." This value can contain up to 128 characters. String Yes
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. This value can contain up to 128 characters, and shouldn't contain special characters or punctuation. All interfaces require this field, with some exceptions. To see if this field is optional, check the documentation for your interface. String Yes
displayCategories Category under which your device displays in the Alexa app. Array of strings from display categories Yes
additionalAttributes Additional information about the endpoint. Amazon recommends that you include this field because it can improve the user experience in the Alexa app. AdditionalAttributes object Recommended
capabilities Capability interfaces that your skill supports for the endpoint, such as Alexa.BrightnessController or Alexa.PowerController. The capabilities field is subject to size limits. Array of Capability objects Yes
connections Information about the methods that the device uses to connect to the internet and smart home hubs. Array of Connection objects No
relationships Endpoints to which an endpoint connects. For example, a computer endpoint might connect to a home network endpoint. Relationships object No
cookie Information about the device that your skill uses. The contents of this property can't exceed 5000 bytes. The API doesn't read or use this data. List of name/value pairs No

AdditionalAttributes object

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 example

Copied to clipboard.

{
  "additionalAttributes":  {
    "manufacturer" : "Sample Manufacturer",
    "model" : "Sample Model",
    "serialNumber": "Serial number",
    "firmwareVersion" : "Firmware version",
    "softwareVersion": "Software version",
    "customIdentifier": "Custom identifier"
  }
}

AdditionalAttributes object details

Field Description Type Required
manufacturer Name of the manufacturer of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. String Recommended
model 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 value can contain up to 256 alphanumeric characters, and can contain punctuation. String Recommended
serialNumber Serial number of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. String Recommended
firmwareVersion Firmware version of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. String Recommended
softwareVersion Software version of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. String Recommended
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. String Recommended

Capability object

A Capability object represents an interface that your skill supports. For example, your skill might support turning on a light by supporting the Alexa.PowerController interface. To find available interfaces for smart home devices, see List of Alexa Interfaces.

Capability object example

Copied to clipboard.

{
    "type": "AlexaInterface",
    "interface": "Alexa.PercentageController",
    "instance": "<Controller instance name>",
    "version": "3",
    "properties": {
        "supported": [
            {
                "name": "percentage"
            }
        ],
        "proactivelyReported": true,
        "retrievable": true
    },
    "capabilityResources": {},
    "configuration": {},
    "semantics": {},
    "verificationsRequired": []
}

Capability object details

Field Description Type Required
type Type of capability. Currently, the only available type is AlexaInterface. String Yes
interface Name of the capability interface. String Yes
instance You can implement multiple instances of some interfaces. In that case, you give each instance of the interface a unique name. For details, see Generic Controller Interfaces. String No
version Version of the interface. Different interfaces have different versions from each other. Always check the documentation for an interface to verify the current version. String Yes
properties Properties of the interface that your skill supports. Properties object No
capabilityResources Provide friendly names that users can use to interact with some interfaces. For details, see Friendly Name Resources and Assets and the documentation for each interface. Object No
configuration or configurations Optional configuration. Some interfaces require a configuration object that contains information about how you're using the interface. For details, see the documentation for each interface. Object No
semantics For some interfaces, you can add additional features by using semantics. Semantics object No
verificationsRequired For some interfaces and locales, you can optionally require the user to verify an action before Alexa performs it. Array of VerificationsRequired objects No
directiveConfigurations For connected vehicles, you can optionally specify the authentication confidence level and the policy name. Array of DirectiveConfigurations objects No

Properties object

The Properties object defines a reportable property of the endpoint. Each Alexa interface defines the reportable property name and value. For details, see the documentation for each interface that you support in your Alexa skill.

Properties object example

Copied to clipboard.

{
  "supported": [
    {
      "name": "percentage"
    }
  ],
  "proactivelyReported": true,
  "retrievable": true
}

Properties object details

Field Description Type Required
supported Properties of the interface that your skill supports. Array No
proactivelyReported Set to true if your skill sends change reports when the properties change. The default is false. Boolean No
retrievable Set to true if you respond to state report requests and report the values of the properties. The default is false. Boolean No

Semantics object

To add user utterances beyond the standard utterances defined by the prebuilt voice interaction model, you can use semantics. When you use semantics for utterances, you manually map the phrases "open", "close", "raise", and "lower" to the directives of your controller. For details, see Semantics for user utterances.

You can also use semantics to enable Alexa hunches for your device to conserve energy on behalf of users. For details, see Semantics for Alexa hunches.

To improve the user experience in the Alexa app, you can use semantics to enable announcements to the user when your device requires attention. To enable announcements, you map device status codes to Alexa predefined states. For details, see Semantics for notifications.

Semantics object example

The following example shows a Semantics object for a device that implements the RangeController interface.

Copied to clipboard.

{
  "semantics": {
    "actionMappings": [
      {
        "@type": "ActionsToDirective",
        "actions": [
          "Alexa.Actions.Close",
          "Alexa.Actions.Lower"
        ],
        "directive": {
          "name": "SetRangeValue",
          "payload": {
            "rangeValue": 0
          }
        }
      },
      {
        "@type": "ActionsToDirective",
        "actions": [
          "Alexa.Actions.Open",
          "Alexa.Actions.Raise"
        ],
        "directive": {
          "name": "SetRangeValue",
          "payload": {
            "rangeValue": 100
          }
        }
      }
    ],
    "stateMappings": [
      {
        "@type": "StatesToValue",
        "states": [
          "Alexa.States.Closed"
        ],
        "value": 0
      },
      {
        "@type": "StatesToRange",
        "states": [
          "Alexa.States.Open"
        ],
        "range": {
          "minimumValue": 1,
          "maximumValue": 100
        }
      }
    ]
  }
}

Semantics object details

Field Description Type Required
actionMappings Array of mappings between action phrases and interface directives. Array of action mapping objects One of ActionMappings or StateMappings is required.
stateMappings Array of mappings between Alexa states and your controller states. Include state mappings so that users can query the device state by using the phrases Open and Closed. Array of state mapping objects One of ActionMappings or StateMappings is required.

ActionMappings object

ActionMappings object example

Copied to clipboard.

{
  "@type": "ActionsToDirective",
  "actions": ["Alexa.Actions.Close", "Alexa.Actions.Lower"],
  "directive": {
    "name": "SetRangeValue",
    "payload": {
      "rangeValue": 0
    }
  }
}

ActionMappings object details

Field Description Type Required
@type Type of action mapping.
Currently, the only valid value is ActionsToDirective.		 String Yes
actions Array of actions that are mapped to a single directive.
Valid values: Alexa.Actions.Open, Alexa.Actions.Close, Alexa.Actions.Raise, Alexa.Actions.Lower, Alexa.Actions.SetEcoOn, and Alexa.Actions.SetEcoOff.		 Array Yes
directive Identifies the directive to call for the actions. Object Yes
directive.name Name of the directive. The directive must be a directive of the interface in the capability object that the semantics object is included in. String Yes
directive.payload Payload appropriate for the directive. Some directives don't require a payload, and the type of the payload depends on the directive. For details, see the documentation for each interface. Object No

StateMappings object

StateMappings object example

Copied to clipboard.

{
  "@type": "StatesToRange",
  "states": ["Alexa.States.Open"],
  "range": {
    "minimumValue": 1,
    "maximumValue": 100
  }
}

StateMappings object details

Field Description Type Required
@type Type of state mapping.
Valid values: one of StatesToValue or StatesToRange.		 String Yes
states Array of Alexa states that are mapped to your controller values.
Valid values: Alexa.States.Open, Alexa.States.Closed, Alexa.States.EcoOn, Alexa.States.EcoOff, Alexa.States.Low, Alexa.States.Empty, Alexa.States.Full, Alexa.States.Done, and Alexa.States.Stuck.		 Array Yes
value Value of your controller that corresponds to the specified Alexa states. Value Yes when @type is StatesToValue
range Range of values of your controller that corresponds to the specified Alexa states. Object Yes when @type is StatesToRange

VerificationsRequired object

When a user asks your skill to perform an action, such as turning on a light, you can require the user to confirm the action first, and then, after you perform the action, give feedback about the results. To require user verification, for each endpoint, specify which directives you require verification for in your Discover.Response.

The following interfaces support user verification: Alexa.PowerController and Alexa.ThermostatController.

VerificationsRequired object example

The following example shows a VerificationsRequired object for an Alexa skill that implements the ThermostatController interface and requires user verification before Alexa sets the target temperature for the thermostat. For a full example, see example for a thermostat that requires user verification.

Copied to clipboard.

{
  "directive": "SetTargetTemperature",
  "methods": [
    {
      "@type": "Confirmation"
    }
  ]
}

VerificationsRequired object details

Field Description Type Required
directive Name of the directive that requires user verification. The directive must be a directive of the interface in the capability object that includes the VerificationsRequired object. String Yes
methods Identifies the methods to use to obtain user verification.
Valid value: Confirmation.		 Array Yes

DirectiveConfigurations object

The following interfaces support directiveConfigurations: Alexa.PowerController, Alexa.LockController, Alexa.ToggleController, Alexa.RangeController, and Alexa.ModeController.

DirectiveConfigurations object example

The following example shows the directiveConfigurations object in the discovery response for an Alexa skill. The skill implements the LockController interface and requires user identification before Alexa unlocks a connected vehicle. For a full example of a lock that requires user identification, see discovery response example with voice recognition and personal profile PIN.

Copied to clipboard.

"directiveConfigurations": [{
            "directives": ["Unlock"],
            "requestedAuthenticationConfidenceLevel": {
                "level": 400,
                "customPolicy": {
                    "policyName": "VOICE_PIN"
                }
            }
        }
    ]

DirectiveConfigurations object details

Field Description Type Required

directives

Names of the directives that require user identification. The name must match the interface indicated in the capability object.

Array of strings

Yes

requestedAuthenticationConfidenceLevel

Specifies the Authentication Confidence Level (ACL) to indicate how confident Alexa is in the identity of the speaker.

Object

No

requestedAuthenticationConfidenceLevel.level

Requested confidence level of Alexa when attempting to identify the speaker. A level of 400 uses a profile PIN and voice recognition. A level of 500 uses a one-time password (OTP) and voice recognition.
Valid values: 400, 500

Integer

Yes

requestedAuthenticationConfidenceLevel.customPolicy

Specifies the authentication policy.

Object

No

requestedAuthenticationConfidenceLevel.customPolicy.policyName

Specifies the name of the authentication policy.
Valid values: OTP, and VOICE_PIN.

String

No

Connections property

The Connections property represents the methods that a device uses to connect to the internet and smart home hubs. The connections property contains an array of connection objects.

Connections property example

Copied to clipboard.

{
  "connections": [
    {
      "type": "TCP_IP",
      "macAddress": "00:11:22:AA:BB:33:44:55"
    },
    {
      "type": "ZIGBEE",
      "macAddress": "00:11:22:33:44:55"
    },
    {
      "type": "ZWAVE",
      "homeId": "<0x00000000>",
      "nodeId": "<0x00>"
    },
    {
      "type": "MATTER",
       "macAddress": "00:11:22:AA:BB:33:44:55",
       "macNetworkInterface": "THREAD",
       "matterVendorId": "MatterVendorId",
       "matterProductId": "MatterProductId",
       "matterDiscriminator": "longDiscriminator"
    },
    {
      "type": "UNKNOWN",
      "value": "00:11:22:33:44:55"
    }
  ]
}

Connections object details

Field Description Type Required
type The type of connection.
Valid values: MATTER, TCP_IP,ZIGBEE, ZWAVE, or UNKNOWN.		 String Yes
macAddress Unique identifier for the network interface controller (NIC). Optionally include this field when the connection type is MATTER, TCP_IP, or ZIGBEE.
For Matter devices, report this field and also keep it up to date if the MAC address changes.		 String Recommended
homeId Home ID for a Z-Wave network to which the endpoint connects. The format is 0x00000000 with UTF-8 characters. Optionally include this field when the connection type is ZWAVE. String No
nodeId Node ID for the endpoint in a Z-Wave network to which the endpoint connects. The format is 0x00 with UTF-8 characters. Optionally include this field when the connection type is ZWAVE. String No
matterDiscriminator A 12-bit value assigned to the endpoint during manufacturing. This value is used to discern between multiple commissionable Matter device advertisements. This field is applicable when the connection type is MATTER. Integer between 0-4095 Recommended
matterVendorId A 16-bit value assigned to the endpoint manufacturer by the Connectivity Standards Alliance. This field is applicable when the connection type is MATTER. Integer between 0-65535 Recommended
matterProductId A 16-bit value assigned by the vendor to uniquely identify the product. This field is applicable when the connection type is MATTER. Integer between 0-65535 Recommended
macNetworkInterface The type of network interface controller (NIC) the macAddress is associated with. Valid values are BLE, WIFI, ETHERNET, or THREAD. This field is applicable when the connection type is MATTER. String Recommended
value Information about the connection when you can't identify the type of the connection more specifically. The information that you provide in this field should be stable and specific. This value can contain up to 256 alphanumeric characters, and can contain punctuation. String Yes when type = UNKNOWN

Relationships object

A relationships object lists the endpoints to which an endpoint connects. For example, a computer endpoint might connect to a home network endpoint, or a headlight might connect to a car.

Relationships object example for networking devices

Copied to clipboard.

{
    "relationships": {
        "isConnectedBy": {
            "endpointId": "unique ID of the home network endpoint"
        }
    }
}

Relationships object example for connected vehicle endpoints

Copied to clipboard.

{
    "relationships": {
        "Alexa.Automotive.IsPartOf": {
            "endpointId": "vehicle-1"
        }
    }
}

Relationships object details

The following table shows the details of the Relationships object. You must include either isConnectedBy or Automotive.IsPartOf.

Field Description Type Required
isConnectedBy Identifies the network to which the endpoint in the discovery response connects. For details, see Understand Networking and Wi-Fi Skills. Object No
isConnectedBy.endpointId Endpoint ID of the network to which this endpoint connects. The specified endpoint must implement Alexa.Networking.HomeNetworkController. String Yes
Alexa.Automotive.IsPartOf Identifies the vehicle to which the endpoint in the discovery response connects. Use this field to connect parts of a vehicle, such as lights or locks, to the vehicle. For details, see Connected Vehicle Skills for Alexa. Object No
Alexa.Automotive.IsPartOf.endpointId Endpoint ID of the vehicle to which this endpoint connects. String Yes