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

{
  "endpointId": "<unique ID of the endpoint>",
  "manufacturerName": "Sample Manufacturer",
  "description": "Smart Light by Sample Manufacturer",
  "friendlyName": "Living Room Light",
  "displayCategories": ["LIGHT"],
  "additionalAttributes":  {},
  "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

The additionalAttributes object

The additionalAttributes object contains additional information about an endpoint. Alexa can use this information to identify devices when different skills describe the same device in different ways.

For example, 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.

Additional attributes object example

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

Additional attributes object schema

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

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

The properties object

Properties object example

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

Properties object schema

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.

Semantics is supported for the following interfaces only: ModeController, RangeController, and ToggleController.

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.

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

The action mapping object

Action mapping object example

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

Action mapping schema

The state mapping object

State mapping object example

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

State mapping schema

The verificationsRequired object

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.

{
  "directive": "SetTargetTemperature",
  "methods": [
    {
      "@type": "Confirmation"
    }
  ]
}

Verifications required object schema

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

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

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. For details, see Understand Networking and Wi-Fi Skills.

Relationships object example

{
  "relationships": {
    "isConnectedBy": {
      "endpointId": "<unique ID of the home network endpoint>"
    }
  }
}

Relationships object schema