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

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

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.

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

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 that are 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 the semantics object is included.

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 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, 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

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

Array of objects

Yes

methods[].@type

Method to obtain user verification.
Valid value: Confirmation.

String

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

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

Type of connection.
Valid values: MATTER, TCP_IP,ZIGBEE, ZWAVE, UNKNOWN.

All

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.
If the MAC address changes, you must report it with the AddOrUpdateReport event.

All

String

Recommended

homeId

Home ID for a Z-Wave network to which the endpoint connects. The format is 0x00000000 with UTF-8 characters.

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.

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 network interface controller (NIC) to which the macAddress is associated.
Valid values: BLE, WIFI, ETHERNET, THREAD.

All

String

Recommended

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 field 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 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

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 example for AVS video devices

Copied to clipboard.

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

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

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 endpointIds.

Array of strings

No

isClusterOf

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.
Use when you want to reference one or more AVS 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 AVS Alexa-enabled device.
Use this relationship for AVS endpoints only.

Object

No

video_isSameAs.source

Type of endpoint source, such as an AVS Alexa-enabled device.
Valid value: AVS.

String

No

video_isSameAs.endpointId

Set to the deviceSerialNumber of the AVS source that you sent in the Device Authorization Request, or to the endpointId that you sent in the discovery response.

String

Yes

video_isSameAs.endpointTypeId

Product ID used to register the AVS source in the Alexa Voice Service portal.
Use this property for AVS sources only.

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

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 created during product registration. It must match the productId or PRODUCT_ID fields used to acquire access tokens during the device's 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 field used to acquire access tokens during the device's authorization flow.

String

Yes

Last updated: Mar 16, 2023