Additional Discovery Response Examples

Note: Register now for Alexa Live, Amazon’s annual Alexa developer conference on July 20, 2022.

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.

You can use these example Discover.Response events in your skill code. To see example discovery responses for other capabilities, see the documentation for each interface.

For more ideas about how to combine different interfaces in your Alexa skills, see Smart Home Skill Device Templates.

Example for a camera that supports pan, tilt, and zoom

The following example shows a Discover.Response event for an Alexa skill that controls a security camera, such as a front door camera or a nursery camera. The camera supports the Alexa.RTCSessionController interface for communication between Alexa devices and the camera. And the camera can physically pan left and right, tilt up and down, and zoom in and out. The skill implements the Alexa.RangeController interface to support pan, tilt, and zoom.

A camera can support any subset of pan, tilt, and zoom. For pan and tilt, specify ranges as percent of the Field of View (FOV) of your camera. For example, if your camera has a 90 degree horizontal FOV, and can rotate 360 total degrees, the range of motion is 400%. You can define your total supported range as 0–400 or –200–200. Define the pan range as –200–200 so that 0 represents the center. The tilt range is –-50–50, and the zoom range is 0–200.

Copied to clipboard.

{
  "event":{
    "header":{
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "a unique identifier, preferably a version 4 UUID"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "unique ID of the endpoint",
          "manufacturerName": "Sample Manufacturer",
          "description": "a description that appears in the Alexa app",
          "friendlyName": "My front door camera",
          "displayCategories": ["CAMERA"],
          "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"
          },
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.RTCSessionController",
              "version": "3",
              "configuration": {
                "isFullDuplexAudioSupported": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.MediaMetadata",
              "version": "3",
              "proactivelyReported": true
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.RangeController",
              "version": "3",
              "instance": "Camera.Pan",
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Camera Pan",
                      "locale": "en-US"
                    }
                  },
                  {
                    "@type": "text",
                    "value": {
                      "text": "Camera Rotation",
                      "locale": "en-US"
                    }
                  },
                  {
                    "@type": "text",
                    "value": {
                      "text": "Rotation",
                      "locale": "en-US"
                    }
                  }
                ]
              },
              "properties": {
                "supported": [
                  {
                    "name": "rangeValue"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              },
              "configuration": {
                "supportedRange": {
                  "minimumValue": -200,
                  "maximumValue": 200,
                  "precision": 1
                },
                "presets": [
                  {
                    "rangeValue": -200,
                    "presetResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "Far Left",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "rangeValue": 0,
                    "presetResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "Center",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "rangeValue": 200,
                    "presetResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "Far Right",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.RangeController",
              "version": "3",
              "instance": "Camera.Tilt",
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Camera Tilt",
                      "locale": "en-US"
                    }
                  },
                  {
                    "@type": "text",
                    "value": {
                      "text": "Tilt",
                      "locale": "en-US"
                    }
                  }
                ]
              },
              "properties": {
                "supported": [
                  {
                    "name": "rangeValue"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              },
              "configuration": {
                "supportedRange": {
                  "minimumValue": -50,
                  "maximumValue": 50,
                  "precision": 1
                },
                "presets": [
                  {
                    "rangeValue": -50,
                    "presetResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "Down",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "rangeValue": 0,
                    "presetResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "Center",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "rangeValue": 50,
                    "presetResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "Up",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.RangeController",
              "version": "3",
              "instance": "Camera.Zoom",
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Camera Zoom",
                      "locale": "en-US"
                    }
                  },
                  {
                    "@type": "text",
                    "value": {
                      "text": "Zoom",
                      "locale": "en-US"
                    }
                  }
                ]
              },
              "properties": {
                "supported": [
                  {
                    "name": "rangeValue"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              },
              "configuration": {
                "supportedRange": {
                  "minimumValue": 0,
                  "maximumValue": 200,
                  "precision": 50
                },
                "presets": [
                  {
                    "rangeValue": 0,
                    "presetResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "Zoomed Out",
                            "locale": "en-US"
                          }
                        },
                        {
                          "@type": "asset",
                          "value": {
                            "assetId": "Alexa.Value.Minimum"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "rangeValue": 200,
                    "presetResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "Zoomed In",
                            "locale": "en-US"
                          }
                        },
                        {
                          "@type": "asset",
                          "value": {
                            "assetId": "Alexa.Value.Maximum"
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            },
            {
                "type": "AlexaInterface",
                "interface": "Alexa.EndpointHealth",
                "version": "3.2",
                "properties": {
                    "supported": [{
                            "name": "connectivity"
                        },
                        {
                            "name": "battery"
                        },
                        {
                            "name": "radioDiagnostics"
                        },
                        {
                            "name": "networkThroughput"
                        }
                    ],
                    "proactivelyReported": true,
                    "retrievable": true
                }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Example for an entertainment device

The following example shows a Discover.Response event for an Alexa skill that controls an entertainment device.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "a unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the endpoint",
                "manufacturerName": "Sample Manufacturer",
                "description": "BrandName by Sample Manufacturer",
                "friendlyName": "Entertainment System",
                "displayCategories": ["TV"],
                "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"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.PowerController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "powerState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ChannelController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "channel"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.InputController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "input"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "inputs": [{
                                "name": "HDMI1"
                            },
                            {
                                "name": "HDMI2"
                            }
                        ]
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.PlaybackController",
                        "version": "3",
                        "properties": {},
                        "supportedOperations": [
                            "Play",
                            "Pause",
                            "Stop"
                        ]
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.Speaker",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                    "name": "volume"
                                },
                                {
                                    "name": "muted"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Example for a fireplace

The following example shows a Discover.Response event for an Alexa skill that controls a fireplace. This fireplace uses the following interfaces:

Alexa.PowerController to turn the fireplace on and off.
Alexa.ColorController to change the color of the flames.
Alexa.RangeController to change the number of burners that are on.
Alexa.ModeController to provide campfire, candle, and ice flame modes.

This example is part of a tutorial that builds a Smart Home virtual fireplace skill in Python. For details, see Skill Sample: Smart Home Fireplace on GitHub.

The friendly names give users more flexibility in how they speak to Alexa. For details, see Friendly Name Resources and Assets.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "a unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the endpoint",
                "manufacturerName": "Sample Manufacturer",
                "description": "Fireplace by Sample Manufacturer",
                "friendlyName": "Living room fireplace",
                "displayCategories": ["OTHER"],
                "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"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.PowerController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "powerState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ColorController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "color"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.RangeController",
                        "instance": "Fireplace.Burners",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "rangeValue"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true,
                            "nonControllable": false
                        },
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "asset",
                                "value": {
                                    "assetId": "Alexa.Setting.Preset"
                                }
                            }]
                        },
                        "configuration": {
                            "supportedRange": {
                                "minimumValue": 1,
                                "maximumValue": 3,
                                "precision": 1
                            },
                            "presets": [{
                                    "rangeValue": 1,
                                    "presetResources": {
                                        "friendlyNames": [{
                                                "@type": "asset",
                                                "value": {
                                                    "assetId": "Alexa.Value.Low"
                                                }
                                            },
                                            {
                                                "@type": "asset",
                                                "value": {
                                                    "assetId": "Alexa.Value.Minimum"
                                                }
                                            },
                                            {
                                                "@type": "text",
                                                "value": {
                                                    "text": "Lowest",
                                                    "locale": "en-US"
                                                }
                                            }
                                        ]
                                    }
                                },
                                {
                                    "rangeValue": 2,
                                    "presetResources": {
                                        "friendlyNames": [{
                                                "@type": "asset",
                                                "value": {
                                                    "assetId": "Alexa.Value.Medium"
                                                }
                                            },
                                            {
                                                "@type": "text",
                                                "value": {
                                                    "text": "Normal",
                                                    "locale": "en-US"
                                                }
                                            }
                                        ]
                                    }
                                },
                                {
                                    "rangeValue": 3,
                                    "presetResources": {
                                        "friendlyNames": [{
                                                "@type": "asset",
                                                "value": {
                                                    "assetId": "Alexa.Value.Maximum"
                                                }
                                            },
                                            {
                                                "@type": "asset",
                                                "value": {
                                                    "assetId": "Alexa.Value.High"
                                                }
                                            },
                                            {
                                                "@type": "text",
                                                "value": {
                                                    "text": "Highest",
                                                    "locale": "en-US"
                                                }
                                            }
                                        ]
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ModeController",
                        "instance": "Fireplace.FlameType",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "mode"
                            }],
                            "retrievable": true,
                            "proactivelyReported": true,
                            "nonControllable": false
                        },
                        "capabilityResources": {
                            "friendlyNames": [{
                                    "@type": "text",
                                    "value": {
                                        "text": "Flame type",
                                        "locale": "en-US"
                                    }
                                },
                                {
                                    "@type": "text",
                                    "value": {
                                        "text": "Flame",
                                        "locale": "en-US"
                                    }
                                }
                            ]
                        },
                        "configuration": {
                            "ordered": false,
                            "supportedModes": [{
                                    "value": "FlameType.Campfire",
                                    "modeResources": {
                                        "friendlyNames": [{
                                                "@type": "text",
                                                "value": {
                                                    "text": "Normal",
                                                    "locale": "en-US"
                                                }
                                            },
                                            {
                                                "@type": "text",
                                                "value": {
                                                    "text": "Campfire",
                                                    "locale": "en-US"
                                                }
                                            }
                                        ]
                                    }
                                },
                                {
                                    "value": "FlameType.Candle",
                                    "modeResources": {
                                        "friendlyNames": [{
                                                "@type": "text",
                                                "value": {
                                                    "text": "Candle",
                                                    "locale": "en-US"
                                                }
                                            },
                                            {
                                                "@type": "text",
                                                "value": {
                                                    "text": "Candle light",
                                                    "locale": "en-US"
                                                }
                                            }
                                        ]
                                    }
                                },
                                {
                                    "value": "FlameType.IceFlame",
                                    "modeResources": {
                                        "friendlyNames": [{
                                                "@type": "text",
                                                "value": {
                                                    "text": "Ice mode",
                                                    "locale": "en-US"
                                                }
                                            },
                                            {
                                                "@type": "text",
                                                "value": {
                                                    "text": "Ice flame",
                                                    "locale": "en-US"
                                                }
                                            },
                                            {
                                                "@type": "text",
                                                "value": {
                                                    "text": "Ice",
                                                    "locale": "en-US"
                                                }
                                            }
                                        ]
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ModeController",
                        "instance": "Fireplace.CurrentFlameType",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "mode"
                            }],
                            "retrievable": true,
                            "proactivelyReported": true,
                            "nonControllable": true
                        },
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "text",
                                "value": {
                                    "text": "Current flame type",
                                    "locale": "en-US"
                                }
                            }]
                        },
                        "configuration": {
                            "ordered": false,
                            "supportedModes": [{
                                    "value": "CurrentFlameType.Campfire",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Campfire",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "CurrentFlameType.Candle",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Candle",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "CurrentFlameType.Ice",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Ice",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Example for a guitar amp

The following example shows a Discover.Response event for an Alexa skill that controls a guitar amp.

This example provides friendly names that give users more flexibility in how they speak to Alexa. For details, see Friendly Name Resources and Assets.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "a unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the endpoint",
                "manufacturerName": "Sample Manufacturer",
                "description": "A smart amplifier by Sample Manufacturer",
                "friendlyName": "Guitar Amp",
                "displayCategories": ["OTHER"],
                "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": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.PowerController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "powerState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.Speaker",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                    "name": "volume"
                                },
                                {
                                    "name": "muted"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EqualizerController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "bands"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configurations": {
                            "bands": {
                                "supported": [{
                                        "name": "BASS"
                                    },
                                    {
                                        "name": "MIDRANGE"
                                    },
                                    {
                                        "name": "TREBLE"
                                    }
                                ],
                                "range": {
                                    "minimum": 1,
                                    "maximum": 10
                                }
                            }
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ToggleController",
                        "version": "3",
                        "instance": "SampleManufacturer.Amp.OverDrive",
                        "capabilityResources": {
                            "friendlyNames": [{
                                    "@type": "text",
                                    "value": {
                                        "text": "Overdrive",
                                        "locale": "en-US"
                                    }
                                },
                                {
                                    "@type": "text",
                                    "value": {
                                        "text": "Over Drive",
                                        "locale": "en-US"
                                    }
                                }
                            ]
                        },
                        "properties": {
                            "supported": [{
                                "name": "toggleState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true,
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.RangeController",
                        "version": "3",
                        "instance": "SampleManufacturer.Amp.Gain",
                        "capabilityResources": {
                            "friendlyNames": [{
                                    "@type": "text",
                                    "value": {
                                        "text": "Gain",
                                        "locale": "en-US"
                                    }
                                },
                                {
                                    "@type": "text",
                                    "value": {
                                        "text": "Drive",
                                        "locale": "en-US"
                                    }
                                }
                            ]
                        },
                        "properties": {
                            "supported": [{
                                "name": "rangeValue"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedRange": {
                                "minimumValue": 1,
                                "maximumValue": 10,
                                "precision": 1
                            },
                            "presets": []
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ModeController",
                        "version": "3",
                        "instance": "SampleManufacturer.Amp.Presets",
                        "capabilityResources": {
                            "friendlyNames": [{
                                    "@type": "text",
                                    "value": {
                                        "text": "Preset",
                                        "locale": "en-US"
                                    }
                                },
                                {
                                    "@type": "text",
                                    "value": {
                                        "text": "Effect",
                                        "locale": "en-US"
                                    }
                                }
                            ]
                        },
                        "properties": {
                            "supported": [{
                                "name": "mode"
                            }],
                            "retrievable": true,
                            "proactivelyReported": true
                        },
                        "configuration": {
                            "ordered": false,
                            "supportedModes": [{
                                    "value": "Preset.Normal",
                                    "modeResources": {
                                        "friendlyNames": [{
                                                "@type": "text",
                                                "value": {
                                                    "text": "Normal",
                                                    "locale": "en-US"
                                                }
                                            },
                                            {
                                                "@type": "text",
                                                "value": {
                                                    "text": "Standard",
                                                    "locale": "en-US"
                                                }
                                            }
                                        ]
                                    }
                                },
                                {
                                    "value": " Preset.LowGain",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Low Gain",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": " Preset.LeadBoost",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Lead Boost",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": " Preset.Metal",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Metal",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Example for a thermostat that requires user verification

Note: At this time, user verification is supported for ja-JP (Japan) only.

The following example shows a Discover.Response event for an Alexa skill that controls a thermostat. This skill uses the Alexa.PowerController interface to turn the thermostat on and off and the Alexa.ThermostatController interface to control the temperature and the mode.

This skill requires the user to verify any actions for this endpoint before Alexa performs them, therefore this Discover.Response includes a verificationsRequired object for each interface that supports it. For details, see VerificationsRequired object.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "a unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the endpoint",
                "manufacturerName": "Sample Manufacturer",
                "description": "Smart Thermostat by Thermostat Maker",
                "friendlyName": "Hallway Thermostat",
                "displayCategories": ["THERMOSTAT", "TEMPERATURE_SENSOR"],
                "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"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController",
                        "version": "3.1",
                        "properties": {
                            "supported": [{
                                    "name": "targetSetpoint"
                                },
                                {
                                    "name": "thermostatMode"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedModes": ["OFF", "COOL"],
                            "supportsScheduling": false
                        },
                        "verificationsRequired": [{
                                "directive": "SetTargetTemperature",
                                "methods": [{
                                    "@type": "Confirmation"
                                }]
                            },
                            {
                                "directive": "SetThermostatMode",
                                "methods": [{
                                    "@type": "Confirmation"
                                }]
                            }
                        ]
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.PowerController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "powerState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "verificationsRequired": [{
                                "directive": "TurnOn",
                                "methods": [{
                                    "@type": "Confirmation"
                                }]
                            },
                            {
                                "directive": "TurnOff",
                                "methods": [{
                                    "@type": "Confirmation"
                                }]
                            }
                        ]
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                    "name": "connectivity"
                                },
                                {
                                    "name": "battery"
                                },
                                {
                                    "name": "radioDiagnostics"
                                },
                                {
                                    "name": "networkThroughput"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Example for a video device

The following example shows a Discover.Response event for an Alexa skill that controls a video device.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "a unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the endpoint",
                "manufacturerName": "Sample Manufacturer",
                "description": "a description that appears in the Alexa app",
                "friendlyName": "Upstairs TV",
                "displayCategories": ["TV"],
                "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": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.RemoteVideoPlayer",
                        "version": "3.1",
                        "properties": {},
                        "configurations": {
                            "operations": ["SearchAndPlay"],
                            "entityTypes": ["MediaType", "League", "Sport", "SportsTeam"],
                            "catalogs": [{
                                    "type": "VIDEO_INGESTION_IDENTIFIER",
                                    "sourceId": "ABCD"
                                },
                                {
                                    "type": "VIDEO_PUBLIC_CATALOG_IDENTIFIER",
                                    "sourceId": "imdb"
                                }
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ChannelController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "channel"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "interface": "Alexa.PlaybackController ",
                        "type": "AlexaInterface",
                        "version": "3",
                        "supportedOperations": ["Play", "Pause", "Stop"]
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.PlaybackStateReporter",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "playbackState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.VideoRecorder",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                    "name": "isExtendedRecordingGUIShown"
                                },
                                {
                                    "name": "storageLevel"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.Launcher",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "target"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Example for a water heater

The following example shows a Discover.Response event for an Alexa skill that controls a water heater as described in Water heater.

In this example you use the Alexa.ToggleController interface to support Alexa hunches. For details about hunches, see What Are Alexa Hunches? and Enable Alexa to Proactively Act on Hunches Without Customers Needing to Ask.

This example also uses the Alexa.DeviceUsage.Meter interface to help users manage their energy usage with the Alexa energy dashboard. For details, see Smart Home Energy Overview.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "a unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the endpoint",
                "manufacturerName": "Sample Manufacturer",
                "description": "a description that appears in the Alexa app",
                "friendlyName": "Water Heater",
                "displayCategories": ["WATER_HEATER"],
                "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"
                },
                "cookie": {},
                "capabilities": [

                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ToggleController",
                        "version": "3",
                        "instance": "EnergySaverMode",
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "text",
                                "value": {
                                    "text": "Energy saver mode",
                                    "locale": "en-US"
                                }
                            }]
                        },
                        "properties": {
                            "supported": [{
                                "name": "toggleState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "semantics": {
                            "actionMappings": [{
                                    "@type": "ActionsToDirective",
                                    "actions": ["Alexa.Actions.SetEcoOff"],
                                    "directive": {
                                        "name": "TurnOff",
                                        "payload": {}
                                    }
                                },
                                {
                                    "@type": "ActionsToDirective",
                                    "actions": ["Alexa.Actions.SetEcoOn"],
                                    "directive": {
                                        "name": "TurnOn",
                                        "payload": {}
                                    }
                                }
                            ],
                            "stateMappings": [{
                                    "@type": "StatesToValue",
                                    "states": ["Alexa.States.EcoOff"],
                                    "value": "OFF"
                                },
                                {
                                    "@type": "StatesToValue",
                                    "states": ["Alexa.States.EcoOn"],
                                    "value": "ON"
                                }
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.DeviceUsage.Meter",
                        "version": "1.0",
                        "configurations": {
                            "energySources": {
                                "electricity": {
                                    "unit": "MILLIWATT_HOUR",
                                    "measuringMethod": "ESTIMATED",
                                    "defaultResolution": 3600
                                }
                            }
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.PowerController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "powerState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Example for a Wi-Fi router

The following example shows a Discover.Response event for an Alexa skill that controls a Wi-Fi router as described in Wi-Fi Router. You can also use the smart home networking APIs if they better suit the needs of your specific device. For details, see Understand Networking and Wi-Fi Skills.

This example provides friendly names that give users more flexibility in how they speak to Alexa. For details, see Friendly Name Resources and Assets.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "a unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the endpoint",
                "manufacturerName": "Sample Manufacturer",
                "description": "Wi-Fi Router by Sample Manufacturer",
                "friendlyName": "Wireless Router",
                "displayCategories": ["OTHER"],
                "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"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ToggleController",
                        "version": "3",
                        "instance": "SampleManufacturer.Router.GuestNetwork",
                        "capabilityResources": {
                            "friendlyNames": [{
                                    "@type": "asset",
                                    "value": {
                                        "assetId": "Alexa.Setting.GuestWiFi"
                                    }
                                },
                                {
                                    "@type": "text",
                                    "value": {
                                        "text": "Guest",
                                        "locale": "en-US"
                                    }
                                },
                                {
                                    "@type": "text",
                                    "value": {
                                        "text": "Guest access",
                                        "locale": "en-US"
                                    }
                                }
                            ]
                        },
                        "properties": {
                            "supported": [{
                                "name": "toggleState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true,
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ModeController",
                        "version": "3",
                        "instance": "SampleManufacturer.Router.Modes",
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "text",
                                "value": {
                                    "text": "Traffic Priority",
                                    "locale": "en-US"
                                }
                            }]
                        },
                        "properties": {
                            "supported": [{
                                "name": "mode"
                            }],
                            "proactivelyReported": false,
                            "retrievable": false
                        },
                        "configuration": {
                            "ordered": false,
                            "supportedModes": [{
                                    "value": "SampleManufacturer.Router.Normal",
                                    "modeResources": {
                                        "friendlyNames": [{
                                                "@type": "text",
                                                "value": {
                                                    "text": "Normal",
                                                    "locale": "en-US"
                                                }
                                            },
                                            {
                                                "@type": "text",
                                                "value": {
                                                    "text": "Regular",
                                                    "locale": "en-US"
                                                }
                                            }
                                        ]
                                    }
                                },
                                {
                                    "value": "SampleManufacturer.Router.Gaming",
                                    "modeResources": {
                                        "friendlyNames": [{
                                                "@type": "text",
                                                "value": {
                                                    "text": "Gaming",
                                                    "locale": "en-US"
                                                }
                                            },
                                            {
                                                "@type": "text",
                                                "value": {
                                                    "text": "Video Games",
                                                    "locale": "en-US"
                                                }
                                            }
                                        ]
                                    }
                                },
                                {
                                    "value": "SampleManufacturer.Router.Video",
                                    "modeResources": {
                                        "friendlyNames": [{
                                                "@type": "text",
                                                "value": {
                                                    "text": "Video",
                                                    "locale": "en-US"
                                                }
                                            },
                                            {
                                                "@type": "text",
                                                "value": {
                                                    "text": "Movies",
                                                    "locale": "en-US"
                                                }
                                            }
                                        ]
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                    "name": "connectivity"
                                },
                                {
                                    "name": "radioDiagnostics"
                                },
                                {
                                    "name": "networkThroughput"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

List of Alexa Interfaces and Supported Languages

Additional Discovery Response Examples

Example for a camera that supports pan, tilt, and zoom

Example for an entertainment device

Example for a fireplace

Example for a guitar amp

Example for a thermostat that requires user verification

Example for a video device

Example for a water heater

Example for a Wi-Fi router

Related topics