Additional Discovery Response Examples

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 some example Discover.Response events. 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 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": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "friendlyName": "Entertainment System",
          "description": "BrandName by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "TV"
          ],
          "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:

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.

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": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "friendlyName": "Living room fireplace",
          "description": "Fireplace by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": ["OTHER"],
          "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",
              "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": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "friendlyName": "Guitar Amp",
          "description": "A smart amplifier by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": ["OTHER"],
          "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

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

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

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "friendlyName": "Hallway Thermostat",
          "description": "Smart Thermostat by Thermostat Maker",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": ["THERMOSTAT", "TEMPERATURE_SENSOR"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ThermostatController",
              "version": "3",
              "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",
              "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": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<the manufacturer name of the endpoint>",
          "description": "<a description that is shown in the Alexa app>",
          "friendlyName": "Upstairs Video Player",
          "displayCategories": ["OTHER"],
          "capabilities": [
            {
              "interface": "Alexa.RemoteVideoPlayer",
              "type": "AlexaInterface",
              "version": "1.0"
            },
            {
              "interface": "Alexa.ChannelController",
              "type": "AlexaInterface",
              "version": "3"
            },
            {
              "interface": "Alexa.PlaybackController ",
              "type": "AlexaInterface",
              "version": "3",
              "supportedOperations": ["Play", "Pause", "Stop"]
            },
            {
              "interface": "Alexa.VideoRecorder",
              "type": "AlexaInterface",
              "version": "1.0"
            },
            {
              "interface": "Alexa.Launcher",
              "type": "AlexaInterface",
              "version": "1.0"
            },
            {
              "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 Alexa.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": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "friendlyName": "Wireless Router",
          "description": "Wi-Fi Router by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": ["OTHER"],
          "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",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}