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.
{
"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:
- PowerController to turn the fireplace on and off.
- ColorController to change the color of the flames.
- RangeController to change the number of burners that are on.
- 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.
This example provides friendly names that give users more flexibility in how they speak to Alexa. For details, see Friendly Name Resources and Assets.
{
"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.
{
"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
Note: Currently user verification is supported only for the (
ja-JP) locale.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.
{
"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.
{
"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 appears 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 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 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 DeviceUsage.Meter interface that is intended to help users manage their energy usage with the Alexa energy dashboard. For details, see Smart Home Energy Overview.
{
"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 appears in the Alexa app>",
"friendlyName": "Water Heater",
"displayCategories": ["WATER_HEATER"],
"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 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.
{
"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"
}
]
}
]
}
}
}