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 user's 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 skill",
"extraDetail2": "You can have multiple entries",
"extraDetail3": "Don't save device state here"
}
}
Endpoint object details
| Property | Description | Type | Required |
|---|---|---|---|
|
|
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. |
String |
Yes |
|
|
Name of the manufacturer of the device. |
String |
Yes |
|
|
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." |
String |
Yes |
|
|
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 field, with some exceptions. To see if this field is optional, check the documentation for your interface. |
String |
Yes |
|
|
Category under which your device displays in the Alexa app. |
Array of strings |
Yes |
|
|
Additional information about the endpoint. Amazon recommends that you include this field because it can improve the user experience in the Alexa app. |
|
Recommended |
|
|
Capability interfaces that your skill supports for the endpoint, such as |
Array of |
Yes |
|
|
Information about the methods that the device uses to connect to the internet and smart home hubs. |
Array of |
No |
|
|
Endpoints to which an endpoint connects. For example, a computer endpoint might connect to a home network endpoint. |
|
No |
|
|
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.
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 |
|---|---|---|---|
|
|
Name of the manufacturer of the device. |
String |
Recommended |
|
|
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 |
String |
Recommended |
|
|
Serial number of the device. |
String |
Recommended |
|
|
Firmware version of the device. |
String |
Recommended |
|
|
Software version of the device. |
String |
Recommended |
|
|
Your custom identifier for the device. This identifier should be globally unique across different user accounts. |
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.
3 and other interfaces are version 3.X.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 of capability. Currently, the only available type is |
String |
Yes |
|
|
Name of the capability interface. |
String |
Yes |
|
|
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 of the interface. Different interfaces have different versions from each other. |
String |
Yes |
|
|
Properties of the interface that your skill supports. |
|
No |
|
|
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 |
|
|
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 |
|
|
For some interfaces, you can add additional features by using semantics. |
|
No |
|
|
For some interfaces and locales, you can optionally require the user to verify an action before Alexa performs it. |
Array of |
No |
|
|
For connected vehicles, you can optionally specify the authentication confidence level and the policy name. |
Array of |
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
{
"supported": [
{
"name": "percentage"
}
],
"proactivelyReported": true,
"retrievable": true
}
Properties object details
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Properties of the interface that your skill supports. |
Array |
No |
|
|
Set to |
Boolean |
No |
|
|
Set to |
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.
{
"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 |
|---|---|---|---|
|
|
Array of mappings between action phrases and interface directives. |
Array of |
One of |
|
|
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 |
Array of |
One of |
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 of action mapping. |
String |
Yes |
|
|
Array of actions that are mapped to a single directive. |
Array |
Yes |
|
|
Identifies the directive to call for the actions. |
Object |
Yes |
|
|
Name of the directive. The directive must be a directive of the interface in the |
String |
Yes |
|
|
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 of state mapping. |
String |
Yes |
|
|
Array of Alexa states that are mapped to your controller values. |
Array |
Yes |
|
|
Value of your controller that corresponds to the specified Alexa states. |
Value |
Yes when |
|
|
Range of values of your controller that corresponds to the specified Alexa states. |
Object |
Yes when |
VerificationsRequired object
ja-JP (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 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.
{
"directive": "SetTargetTemperature",
"methods": [
{
"@type": "Confirmation"
}
]
}
VerificationsRequired object details
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Name of the directive that requires user verification. The directive must be a directive of the interface in the |
String |
Yes |
|
|
Identifies the methods to use to obtain user verification. |
Array of objects |
Yes |
|
|
Method to obtain user verification. |
String |
Yes |
DirectiveConfigurations object
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.
"directiveConfigurations": [{
"directives": ["Unlock"],
"requestedAuthenticationConfidenceLevel": {
"level": 400,
"customPolicy": {
"policyName": "VOICE_PIN"
}
}
}
]
DirectiveConfigurations object details
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Names of the directives that require user identification. The name must match the interface indicated in the capability object. |
Array of strings |
Yes |
|
|
Specifies the Authentication Confidence Level (ACL) to indicate how confident Alexa is in the identity of the speaker. |
Object |
No |
|
|
Requested confidence level of Alexa when attempting to identify the speaker.
|
Integer |
Yes |
|
|
Specifies the authentication policy. |
Object |
No |
|
|
Specifies the name of the authentication policy. |
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
{
"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": "WIFI",
"matterVendorId": "Matter VendorID",
"matterProductId": "Matter ProductID",
"matterDiscriminator": "longDiscriminator"
},
{
"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 field applies to.
| Property | Description | Connection type | Type | Required |
|---|---|---|---|---|
|
|
Type of connection. |
All |
String |
Yes |
|
|
Unique identifier for the network interface controller (NIC).
Optionally include this field when the connection type is |
All |
String |
Recommended |
|
|
Home ID for a Z-Wave network to which the endpoint connects. The format is |
|
String |
No |
|
|
Node ID for the endpoint in a Z-Wave network to which the endpoint connects. The format is |
|
String |
No |
|
|
12-bit value assigned to the endpoint during manufacturing. Used to discern between multiple commissionable Matter device advertisements. |
|
Integer |
Yes |
|
|
16-bit value assigned to the endpoint manufacturer by the Connectivity Standards Alliance. |
|
Integer |
Yes |
|
|
16-bit value assigned by the vendor to uniquely identify the product. |
|
Integer |
Yes |
|
|
Type of network interface controller (NIC) to which the |
All |
String |
Recommended |
|
|
When you can't identify the type of the connection more specifically, include information about the connection. The information that you provide in this field should be stable and specific. |
|
String |
Yes |
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. 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 networking devices
{
"relationships": {
"isConnectedBy": {
"endpointId": "unique ID of the home network endpoint"
}
}
}
Relationships object example for connected vehicle endpoints
{
"relationships": {
"Alexa.Automotive.IsPartOf": {
"endpointId": "vehicle-1"
}
}
}
Relationships object example for AVS video devices
{
"endpoints": [{
"endpointId": "AVS-hub-endpointID",
"registration": {
"productId": "productID-001",
"deviceSerialNumber": "serial-001"
},
"friendlyName": "My AVS 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": "AVS-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 |
|---|---|---|---|
|
|
Identifies the network to which the endpoint in the discovery response connects. For details, see Understand Networking and Wi-Fi Skills. |
Object |
No |
|
|
Endpoint ID of the network to which this endpoint connects. The specified endpoint must implement |
String |
Yes |
|
|
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 |
|
|
Endpoint ID of the vehicle to which this endpoint connects. |
String |
Yes |
|
|
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 endpointIds. Note: An endpoint can have one controlled-by relationship only.
|
Array of strings |
No |
|
|
Use to indicate that a smart home endpoint controls one or more AVS 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. |
Array of strings |
No |
|
|
Use to associate a smart home endpoint with video capability with an AVS Alexa-enabled device. |
Object |
No |
|
|
Type of endpoint source, such as an AVS Alexa-enabled device. |
String |
No |
|
|
Set to the |
String |
Yes |
|
|
Product ID used to register the AVS source in the Alexa Voice Service portal. |
String |
No |
Registration property
Use Registration property to represent an Alexa Voice Service (AVS) Alexa-enabled device. For more details about the Discovery interface for Alexa Built-in devices, see Alexa.Discovery for AVS.
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 |
|---|---|---|---|
|
|
Developer-provided product ID created during product registration. It must match the |
String |
Yes |
|
|
Device-generated serial number that's unique among all devices sharing the same |
String |
Yes |
Related topics
Last updated: May 05, 2023