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
- A group or cluster of devices, 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": {},
"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. 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. 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." 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 field, with some exceptions. To see if this field is optional, check the documentation for your interface. Valid value: Up to 128 alphanumeric characters and spaces. Don't include special characters or punctuation. |
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
{
"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. 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 would be Audi and the model would be 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. 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.
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
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
{
"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.
{
"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
{
"@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. Valid value: 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
{
"@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
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
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
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
Field | 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. A level of 400 uses a profile PIN and voice recognition. A level of 500 uses a one-time password (OTP) and voice recognition. |
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": "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
{
"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 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 |