Alexa Discovery Objects Reference

Note: Sign in to the developer console to build or publish your skill.

This reference defines the objects that you send to Alexa in the Alexa.Discovery interface.

Endpoint object

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

A physical device
A virtual device, 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": "Serial number of the device",
        "firmwareVersion": "Firmware version of the device",
        "softwareVersion": "Software version of the device",
        "customIdentifier": "Optional custom identifier for the device"
    },
    "capabilities": [],
    "connections": [],
    "relationships": {},
    "registration": {},
    "cookie": {
        "extraDetail1": "Information used by your skill",
        "extraDetail2": "You can have multiple entries",
        "extraDetail3": "Don't save device state here"
    }
}

Endpoint object details

Property	Description	Type	Required
`endpointId`	Identifier for the endpoint. The identifier must be globally unique across all devices and users for the skill. The identifier must be consistent for all discovery requests for the same device. Valid value: Up to 256 characters. Can include letters, numbers, spaces, and the following special characters: `_ - = # ; : ? @ &`	String	Yes
`manufacturerName`	Name of the manufacturer of the device. Valid value: Up to 128 characters.	String	Yes
`description`	Description of the device. Include 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
`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 property, with some exceptions. To see if this property is optional, check the documentation for your Alexa capability interface. Valid value: Up to 256 alphanumeric characters and spaces. Don't include special characters or punctuation.	String	Yes
`displayCategories`	Category under which your device displays in the Alexa app. For supported categories, see Display categories.	Array of strings	Yes
`additionalAttributes`	Additional information about the endpoint. Amazon recommends that you include this property because it can improve the user experience in the Alexa app. You must include this property if you want to apply for Works with Alexa Certification.	`AdditionalAttributes` object	Recommended
`capabilities`	Capability interfaces that your skill supports for the endpoint, such as `Alexa.BrightnessController` or `Alexa.PowerController`. The `capabilities` property 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. Alexa 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 uses the AdditionalAttributes object to identify duplicate devices and improve the user experience in the Alexa app.

Important: For Alexa to identify unique devices, include as many properties as you can. Amazon recommends that you include at least model and manufacturer.

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, such as Matter UniqueID"
  }
}

AdditionalAttributes object details

Property	Description	Type	Required
`manufacturer`	Name of the manufacturer of the device. Valid value: Up to 256 characters. Can include letters, numbers, and 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 is `Audi` and the model is `A6 2020`. Valid value: Up to 256 characters. Can include letters, numbers, and punctuation.	String	Recommended
`serialNumber`	Serial number of the device. Valid value: Up to 256 characters. Can include letters, numbers, and punctuation.	String	Recommended
`firmwareVersion`	Firmware version of the device. Valid value: Up to 256 characters. Can include letters, numbers, and punctuation.	String	Recommended
`softwareVersion`	Software version of the device. Valid value: Up to 256 characters. Can include letters, numbers, and punctuation.	String	Recommended
`customIdentifier`	Your custom identifier for the device. This identifier should be globally unique across different user accounts. For Matter devices, you must include this property to report the Matter `UniqueID` attribute. Valid value: Up to 256 characters. Can include letters, numbers, and 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.

Important: Always check the documentation for an interface to verify the current version. Some interfaces are version 3 and other interfaces are version 3.X.

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

Property	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 use 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

Property	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 pre-built 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.

Important: You can use semantics with the generic controller interfaces.

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

Property	Description	Type	Required
`actionMappings`	Array of mappings between action phrases and interface directives.	Array of `ActionMappings` objects	One of `ActionMappings` or `StateMappings`
`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 `StateMappings` objects	One of `ActionMappings` or `StateMappings`

ActionMappings object

The ActionMappings object defines mappings between action phrases and interface directives.

ActionMappings object example

Copied to clipboard.

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

ActionMappings object details

Property	Description	Type	Required
`@type`	Type of action mapping. Valid value: `ActionsToDirective`.	String	Yes
`actions`	Array of actions mapped to a single directive. Valid values: `Alexa.Actions.Open`, `Alexa.Actions.Close`, `Alexa.Actions.Raise`, `Alexa.Actions.Lower`, `Alexa.Actions.SetEcoOn`, `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 in which you include the `semantics` object.	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

The StateMappings object defines mappings between Alexa states and controller states.

StateMappings object example

Copied to clipboard.

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

StateMappings object details

Property	Description	Type	Required
`@type`	Type of state mapping. Valid values: one of `StatesToValue` or `StatesToRange`.	String	Yes
`states`	Array of Alexa states 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`, `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

Note: At this time, action verification is supported in Japanese for devices located in Japan only.

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 action verification, for each endpoint, specify which directives you require verification for in your discovery response.

The following interfaces support action 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 action verification before Alexa sets the target temperature for the thermostat. For a complete discovery response example, see example for a thermostat that requires action verification.

Copied to clipboard.

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

VerificationsRequired object details

Property	Description	Type	Required
`directive`	Name of the directive that requires 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 action verification.	Array of objects	Yes
`methods[].@type`	Method to obtain action verification. Valid value: `Confirmation`.	String	Yes

DirectiveConfigurations object

Note: The directiveConfigurations object is for Alexa user identification implementation for connected vehicles only.

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

Property	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. Valid values: 400 – Uses a profile PIN and voice recognition. 500 – Uses a one-time password (OTP) and voice recognition.	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": "BLUETOOTH_MESH",
      "deviceUuid": "90b6eeb8cb58c9a7887d4797543bbe8a"
    },
    {
      "type": "MATTER",
       "macAddress": "00:11:22:AA:BB:33:44:55",
       "macNetworkInterface": "WIFI",
       "matterVendorId": "Matter VendorID",
       "matterProductId": "Matter ProductID",
       "matterDiscriminator": "longDiscriminator"
    },
    {
      "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": "UNKNOWN",
      "value": "00:11:22:33:44:55"
    }
  ]
}

Connections object details

The following table shows the Connections object details, along with the connection type that each property applies to.

Property	Description	Connection type	Type	Required
`type`	Type of connection. Valid values: `BLUETOOTH_MESH`, `MATTER`, `TCP_IP`,`ZIGBEE`, `ZWAVE`, `UNKNOWN`.	All	String	Yes
`macAddress`	Unique identifier for the network interface controller (NIC). Optionally include this property when the connection type is `MATTER`, `TCP_IP` or `ZIGBEE`. If the MAC address changes, you must report it with the `AddOrUpdateReport` event. Valid value: 1 – 32 characters.	`MATTER`, `TCP_IP`, `ZIGBEE`	String	Recommended
`homeId`	Home ID for a Z-Wave network to which the endpoint connects. Format: `0x00000000` with UTF-8 characters.	`ZWAVE`	String	No
`nodeId`	Node ID for the endpoint in a Z-Wave network to which the endpoint connects. Format: `0x00` with UTF-8 characters.	`ZWAVE`	String	No
`matterDiscriminator`	12-bit value assigned to the endpoint during manufacturing. Used to discern between multiple commissionable Matter device advertisements. Set to the Matter `Discriminator` attribute. Valid values: 0 – 4095.	`MATTER`	Integer	Yes
`matterVendorId`	16-bit value assigned to the endpoint manufacturer by the Connectivity Standards Alliance. Set to the Matter `VendorID` attribute. Valid values: 0 – 65535.	`MATTER`	Integer	Yes
`matterProductId`	16-bit value assigned by the vendor to uniquely identify the product. Set to the Matter `ProductID` attribute. Valid values: 0 – 65535.	`MATTER`	Integer	Yes
`macNetworkInterface`	Type of NIC to which the `macAddress` is associated. Valid values: `BLE`, `WIFI`, `ETHERNET`, `THREAD`.	`MATTER`, `TCP_IP`, `ZIGBEE`	String	Recommended
`deviceUuid`	UUID for the device endpoint that connects to a Bluetooth mesh network. Valid value: 32 alphanumeric characters. Include hexadecimal digits only.	`BLUETOOTH_MESH`	String	Yes
`value`	When you can't identify the type of the connection more specifically, include information about the connection. The information that you provide in this property should be stable and specific. Valid value: Up to 256 characters. Can include letters, numbers, punctuation.	`UNKNOWN`	String	Yes

Relationships object

A relationships object lists the endpoints to which an endpoint connects. For example, a headlight might connect to a car, or one or more speakers might connect to a soundbar to create a home theater. Alexa uses device relationships to organize related devices or scenes in the Alexa app. For more details, see Identify relationships between endpoints.

Relationships object example for connected vehicle endpoints

Copied to clipboard.

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

Relationships object example for Alexa Built-in video devices

Copied to clipboard.

{
    "endpoints": [{
            "endpointId": "ABI-hub-endpointID",
            "registration": {
                "productId": "productID-001",
                "deviceSerialNumber": "serial-001"
            },
            "friendlyName": "My Alexa-Built-in Hub",
            "displayCategories": ["ALEXA_VOICE_ENABLED"],
            "capabilities": [],
            "connections": []
        },
        {
            "endpointId": "soundbar-endpointID",
            "friendlyName": "soundbar",
            "displayCategories": ["OTHER"],
            "relationships": {
                "video_isSameAs": {
                    "endpointId": "serial-001",
                    "endpointTypeId": "productID-001",
                    "source": "AVS"
                }
            }
        },
        {
            "endpointId": "tv-endpointID",
            "friendlyName": "TV",
            "displayCategories": ["TV"],
            "relationships": {
                "isControlledBy": [{
                    "endpointId": "ABI-hub-endpointID"
                }],
                "video_isSameAs": {
                    "endpointId": "serial-001",
                    "endpointTypeId": "productID-001",
                    "source": "AVS"
                }
            }
        }
    ]
}

Relationships object details

The following table shows the details of the Relationships object. You must include at least one property.

Property	Description	Type	Required
`Alexa.Automotive.IsPartOf`	Identifies the vehicle to which the endpoint in the discovery response connects. Use this property 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
`isControlledBy`	Use to indicate that another endpoint controls this endpoint. For example, an Alexa-enabled soundbar might control a TV, or a scene might control multiple lights. Include one or more reported `endpointId`. Note: An endpoint can have one controlled-by relationship only.	Array of strings	No
`isClusterOf`	Use to indicate that a smart home endpoint controls one or more Alexa Built-in (ABI) endpoints. Include all endpoints that make up the cluster. For example, one or more speakers connected to a soundbar to create a home theater. The cluster endpoint shows up in the Alexa app, hiding all children endpoints. Use when you want to reference one or more ABI devices as a child of a smart home endpoint.	Array of strings	No
`video_isSameAs`	Use to associate a smart home endpoint with video capability with an Alexa Built-in device. Use this relationship for Alexa Built-in endpoints only.	Object	No
`video_isSameAs.source`	Type of endpoint source, such as an Alexa Built-in device. Valid value: `AVS`.	String	No
`video_isSameAs.endpointId`	Set to the `deviceSerialNumber` of the Alexa Built-in source, or to the `endpointId` that you sent in the discovery response.	String	Yes
`video_isSameAs.endpointTypeId`	Alexa Built-in Product ID. Use this property for Alexa Built-in sources only.	String	No

Registration property

Use Registration property to represent an Alexa Built-in device.

Registration property example

Copied to clipboard.

{
  "registration": {
    "productId": "productID-001",
    "deviceSerialNumber": "serial-001"
  }
}

Registration object details

The following table shows the Registration object details.

Property	Description	Type	Required
`productId`	Developer-provided product ID. It must match the `productId` or `PRODUCT_ID` properties used to acquire access tokens during the Alexa Built-in device authorization flow.	String	Yes
`deviceSerialNumber`	Device-generated serial number that's unique among all devices sharing the same `productId`. It must match the `deviceSerialNumber` or `PRODUCT_DSN` property used to acquire access tokens during the Alexa Built-in device authorization flow.	String	Yes

Was this page helpful?

Provide feedback

Last updated: Nov 04, 2024

Alexa Discovery Objects Reference

Endpoint object

Endpoint object example

Endpoint object details

AdditionalAttributes object

AdditionalAttributes object example

AdditionalAttributes object details

Capability object

Capability object example

Capability object details

Properties object

Properties object example

Properties object details

Semantics object

Semantics object example

Semantics object details

ActionMappings object

ActionMappings object example

ActionMappings object details

StateMappings object

StateMappings object example

StateMappings object details

VerificationsRequired object

VerificationsRequired object example

VerificationsRequired object details

DirectiveConfigurations object

DirectiveConfigurations object example

DirectiveConfigurations object details

Connections property

Connections property example

Connections object details

Relationships object

Relationships object example for connected vehicle endpoints

Relationships object example for Alexa Built-in video devices

Relationships object details

Registration property

Registration property example

Registration object details

Related topics

Was this page helpful?