Alexa Discovery Objects Reference

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

{
    "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 add-on",
        "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 add-on. 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 add-on 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 add-on 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 add-ons 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.

AdditionalAttributes object example

{
  "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 device MyLights 2100, the manufacturer is `MyLights` and the model is `2100`. 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 add-on supports. For example, your add-on 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

{
    "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 add-on 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

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 add-on.

Properties object example

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

Properties object details

Property	Description	Type	Required
`supported`	Properties of the interface that your add-on supports.	Array	No
`proactivelyReported`	Set to `true` if your add-on 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 , , , and 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.

{
  "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

{
  "@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

{
  "@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

When a user asks your add-on 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 add-on 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.

{
  "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

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

{
  "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 Alexa Built-in video devices

{
    "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
`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`.	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

{
  "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

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer 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

Connections property

Connections property example

Connections object details

Relationships object

Relationships object example for Alexa Built-in video devices

Relationships object details

Registration property

Registration property example

Registration object details

​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

​Connections property

​Connections property example

​Connections object details

​Relationships object

​Relationships object example for Alexa Built-in video devices

​Relationships object details

​Registration property

​Registration property example

​Registration object details

​Related topics

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

Connections property

Connections property example

Connections object details

Relationships object

Relationships object example for Alexa Built-in video devices

Relationships object details

Registration property

Registration property example

Registration object details

Related topics