Alexa Discovery Objects

The Alexa.Discovery interface describes messages used to identify the endpoints associated with the user's device account. You send a Discover.Response event so that a user can discover the devices and scenes associated with your Smart Home skill. For details, see Alexa.Discovery.

The following are the objects that you send to Alexa in your discovery messages.

The 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

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": "<the serial number of the device>",
      "firmwareVersion" : "<the firmware version of the device>",
      "softwareVersion": "<the software version of the device>",
      "customIdentifier": "Your 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 schema

Field	Description	Type	Required
`endpointId`	The 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. An identifier can contain letters or numbers, spaces, and the following special characters: _ - = # ; : ? @ &. The identifier can't exceed 256 characters.	String	Yes
`manufacturerName`	The name of the manufacturer of the device. This value can contain up to 128 characters.	String	Yes
`description`	The 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." This value can contain up to 128 characters.	String	Yes
`friendlyName`	The 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. This value can contain up to 128 characters, and shouldn't contain special characters or punctuation. All interfaces require this field, with some exceptions. Check the documentation for your interface to see if this field is optional.	String	Yes
`displayCategories`	In the Alexa app, the category under which your device displays.	An 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, as explained here.	An additionalAttributes object.	Recommended
`capabilities`	The capability interfaces that your skill supports for the endpoint, such as `Alexa.BrightnessController` or `Alexa.PowerController`. The `capabilities` field is subject to size limits.	An array of capability objects.	Yes
`connections`	Information about the methods that the device uses to connect to the internet and smart home hubs.	An array of connection objects.	No
`relationships`	The endpoints to which an endpoint connects. For example, a computer endpoint might connect to a home network endpoint.	A 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.	A list of name/value pairs.	No

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

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

Additional attributes object example

Copied to clipboard.

{
  "additionalAttributes":  {
    "manufacturer" : "Sample Manufacturer",
    "model" : "Sample Model",
    "serialNumber": "Serial number",
    "firmwareVersion" : "Firmware version",
    "softwareVersion": "Software version",
    "customIdentifier": "Custom identifier"
  }
}

Additional attributes object schema

Field	Description	Type	Required
`manufacturer`	The name of the manufacturer of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation.	String	Recommended
`model`	The 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. This value can contain up to 256 alphanumeric characters, and can contain punctuation.	String	Recommended
`serialNumber`	The serial number of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation.	String	Recommended
`firmwareVersion`	The firmware version of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation.	String	Recommended
`softwareVersion`	The software version of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation.	String	Recommended
`customIdentifier`	Your custom identifier for the device. This identifier should be globally unique across different user accounts. This value can contain up to 256 alphanumeric characters, and can contain punctuation.	String	Recommended

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

Field	Description	Type	Required
`type`	The type of capability. Currently, the only available type is `AlexaInterface`.	String	Yes
`interface`	The 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`	The 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`	The properties of the interface that your skill supports.	A properties object.	No
`capabilityResources`	You can 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`	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`	You can optionally map the words open, close, raise, and lower to existing directives, for some interfaces.	A semantics object.	No
`verificationsRequired`	You can optionally require the user to verify an action before Alexa performs it, for some interfaces and locales.	An array of verificationsRequired objects.	No

The properties object

Properties object example

Copied to clipboard.

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

Properties object schema

Field	Description	Type	Required
`supported`	The properties of the interface that your skill supports.	Array	No
`proactivelyReported`	True if your skill sends change reports when the properties change. The default is false.	Boolean	No
`retrievable`	True if you respond to state report requests and report the values of the properties. The default is false.	Boolean	No

The semantics object

When you use an Alexa interface, the voice interaction model is already built for you. Users can interact with your device by saying standard utterances. You can optionally enable additional utterances by using semantics. When you use semantics, you manually map the phrases "open", "close", "raise", and "lower" to directives. 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.

You can also use semantics to enable announcements so that Alexa can notify a user when their device needs attention. For details, see Semantics for announcements.

Important: Semantics is supported only for the generic controller interfaces.

Semantics object example

The following is an example of a semantics object in the discover response for a device that implements the RangeController interface. For details about each field, see the semantics object schema table following the example.

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 schema

Field	Description	Type	Required
`actionMappings`	An array of mappings between action phrases and interface directives.	An array of action mapping objects.	One of `actionMappings` or `stateMappings` is required.
`stateMappings`	An array of mappings between Alexa states and your controller states. Include state mappings so that users can query the device state using the phrases `Open` and `Closed`.	An array of state mapping objects.	One of `actionMappings` or `stateMappings` is required.

The action mapping object

Action mapping object example

Copied to clipboard.

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

Action mapping schema

Field	Description	Type	Required
`@type`	The type of action mapping. Currently, the only valid value is `ActionsToDirective`.	String	Yes
`actions`	An array of actions that are mapped to a single directive. Valid values are `Alexa.Actions.Open`, `Alexa.Actions.Close`, `Alexa.Actions.Raise`, `Alexa.Actions.Lower`, `Alexa.Actions.SetEcoOn`, and `Alexa.Actions.SetEcoOff`.	Array	Yes
`directive`	The directive to call for the actions.	Object	Yes
`directive.name`	The 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`	The 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

The state mapping object

State mapping object example

Copied to clipboard.

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

State mapping schema

Field	Description	Type	Required
`@type`	The type of state mapping; one of: `StatesToValue` or `StatesToRange`.	String	Yes
`states`	An array of Alexa states that are mapped to your controller values. Valid values are `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`	The value of your controller that corresponds to the specified Alexa states.	Value	Yes when `@type` is `StatesToValue`
`range`	The range of values of your controller that corresponds to the specified Alexa states.	Object	Yes when `@type` is `StatesToRange`

The verificationsRequired object

Note: Currently user verification is supported only for the (ja-JP) locale.

When a user asks your skill to perform an action, such as turning on a light, you can require the user to verify the action before Alexa performs it. To require user verification, specify which directives you require verification for in your Discover.Response.

User verification is supported for the following interfaces only: PowerController and ThermostatController.

Verifications required object example

The following is an example of a verifications required object in the discover response 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"
    }
  ]
}

Verifications required object schema

Field	Description	Type	Required
`directive`	The name of the directive to require verification for. The directive must be a directive of the interface in the capability object that the `verificationsRequired` object is included in.	String	Yes
`methods`	The methods for obtaining user verification. Currently the only supported verification method is `Confirmation`.	Array	Yes

The 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": "UNKNOWN",
      "value": "00:11:22:33:44:55"
    }
  ]
}

Connection object schema

Field	Description	Type	Required
`type`	The type of connection; one of `TCP_IP`, `ZIGBEE`, `ZWAVE`, or `UNKNOWN`.	String	Yes
`macAddress`	The unique identifier for the network interface controller (NIC). Optionally include this field when the connection type is `TCP_IP` or `ZIGBEE`.	String	No
`homeId`	The Home ID for a Z-Wave network that the endpoint connects to. The format is `0x00000000` with UTF-8 characters. Optionally include this field when the connection type is `ZWAVE`.	String	No
`nodeId`	The Node ID for the endpoint in a Z-Wave network that the endpoint connects to. The format is `0x00` with UTF-8 characters. Optionally include this field when the connection type is `ZWAVE`.	String	No
`value`	The connection information for a 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`

The relationships object

A relationships object lists the endpoints that an endpoint is connected to. For example, a computer endpoint might be connected to a home network endpoint, or a headlight might be connected to a car.

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 schema

Field	Description	Type	Required
`isConnectedBy`	The endpoint ID of the network that this endpoint is connected to. The specified endpoint should implement Alexa.Networking.HomeNetworkController. For details, see Understand Networking and Wi-Fi Skills.	Object	Yes
`Alexa.Automotive.IsPartOf`	The endpoint ID of the vehicle that this endpoint is connected to. Use this to connect parts of a vehicle, such as lights or locks, to the vehicle. For details, see Connected Vehicle Skills for Alexa.	Object	No