Alexa.Discovery Interface
The Alexa.Discovery interface describes messages used to identify the endpoints associated with the user's device account. You respond to discovery directives so that a user can discover the devices and scenes associated with your smart home skill, and you should proactively send events to add, update or delete endpoints associated with a user account.
- Properties and Objects
- Directives
- AddOrUpdateReport event
- DeleteReport event
- Display categories
- Additional Discover.Response examples
- Related Topics
Properties and Objects
The endpoint object
The endpoint object represents a connected device or component associated with a user's device cloud account. An endpoint describes one of the following:
- A physical device
- A virtual device
- A group or cluster of devices
- A software component
Endpoint object example
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "Sample Manufacturer",
"description": "Smart Light by Sample Manufacturer",
"friendlyName": "Living Room Light",
"displayCategories": ["LIGHT"],
"additionalAttributes": {
},
"capabilities": [
],
"connections": [
],
"relationships": {
},
"cookie": {
"extraDetail1": "information used by your skill",
"extraDetail2": "you can have multiple entries",
"extraDetail3": "don't save device state here"
}
}
Endpoint object schema
| Field | Description | Type | Required |
|---|---|---|---|
endpointId |
The identifier for the endpoint. The identifier must be unique across all devices for the skill. The identifier must be consistent for all discovery requests for the same device. An identifier can contain letters or numbers, spaces, and the following special characters: _ - = # ; : ? @ &. The identifier can't exceed 256 characters. | String | Yes |
manufacturerName |
The name of the manufacturer of the device. This value can contain up to 128 characters. | String | Yes |
description |
The description of the device. The description should contain the manufacturer name or how the device connects. For example, "Smart Lock by Sample Manufacturer" or "WiFi Thermostat connected via SmartHub". This value can contain up to 128 characters. | String | Yes |
friendlyName |
The name used by the user to identify the device. This value can contain up to 128 characters, and shouldn't contain special characters or punctuation. This field is required for all interfaces, with some exceptions. Check the documentation for your interface to see if this field is optional. | String | Yes |
displayCategories |
In the Alexa app, the category that your device is displayed in. | An array of strings from display categories. | Yes |
additionalAttributes |
Additional information about the endpoint. | An additionalAttributes object. | No |
capabilities |
The capability interfaces that your skill supports for the endpoint, such as Alexa.BrightnessController or Alexa.PowerController. |
An array of capability objects. | Yes |
connections |
Information about the methods that the device uses to connect to the internet and smart home hubs. | An array of connection objects. | No |
relationships |
The endpoints that an endpoint is connected to. For example, a computer endpoint might be connected to a home network endpoint. | A relationships object. | No |
cookie |
Information about the device that your skill uses. The contents of this property can't exceed 5000 bytes. The API doesn't read or use this data. | A list of name/value pairs. | No |
The additionalAttributes object
The additionalAttributes object contains additional information about an endpoint. Alexa can use this information to identify devices when different skills describe the same device in different ways.
Additional attributes object example
{
"additionalAttributes": {
"manufacturer" : "Sample Manufacturer",
"model" : "Sample Model",
"serialNumber": "<the serial number of the device>",
"firmwareVersion" : "<the firmware version of the device>",
"softwareVersion": "<the software version of the device>",
"customIdentifier": "<your custom identifier for the device>"
}
}
Additional attributes object schema
| Field | Description | Type | Required |
|---|---|---|---|
manufacturer |
The name of the manufacturer of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. | String | No |
model |
The name of the model of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. | String | No |
serialNumber |
The serial number of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. | String | No |
firmwareVersion |
The firmware version of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. | String | No |
softwareVersion |
The software version of the device. This value can contain up to 256 alphanumeric characters, and can contain punctuation. | String | No |
customIdentifier |
Your custom identifier for the device. This identifier should be globally unique in your systems across different user accounts. This value can contain up to 256 alphanumeric characters, and can contain punctuation. | String | No |
The capability object
A capability object represents an interface that your skill supports. For example, your skill might support turning on a light by supporting the Alexa.PowerController interface. To find available interfaces for smart home devices, see List of Capability Interfaces and Supported Locales.
Capability object example
{
"type": "AlexaInterface",
"interface": "Alexa.PercentageController",
"instance": "<Controller instance name>",
"version": "3",
"properties": {
"supported": [
{
"name": "percentage"
}
],
"proactivelyReported": true,
"retrievable": true
},
"capabilityResources": {},
"configuration": {},
"semantics": {}
}
Capability object schema
| Field | Description | Type | Required |
|---|---|---|---|
type |
The type of capability. Currently, the only available type is AlexaInterface. |
String | Yes |
interface |
The name of the capability interface. | String | Yes |
instance |
You can implement multiple instances of some interfaces. In that case, you give each instance of the interface a unique name. For more information, see ModeController, RangeController, and ToggleController. | String | No |
version |
The version of the interface. Different interfaces have different versions from each other. Always check the documentation for an interface to verify the current version. | String | Yes |
properties.supported |
The properties of the interface that your skill supports. | Array | No |
properties.proactivelyReported |
True if your skill sends change reports when the properties change. The default is false. | Boolean | No |
properties.retrievable |
True if you respond to state report requests and report the values of the properties. The default is false. | Boolean | No |
capabilityResources |
You can provide friendly names that users can use to interact with some interfaces. For more information, see the documentation for each interface. | Object | No |
configuration |
Some interfaces require a configuration object that contains information about how you are using the interface. For more information, see the documentation for each interface. | Object | No |
verificationsRequired |
Some interfaces support an optional verificationsRequired object that specifies any verifications that are required for certain directives. For more information, see VerificationsRequired and the documentation for each interface.Note: Currently verificationsRequired is supported only in theja-JP locale. |
Object | No |
semantics |
You can optionally map the words open, close, raise, and lower to existing directives for some interfaces. | A semantics object. | No |
The semantics object
When you use an Alexa interface, the voice interaction model is already built for you. Users can interact with your device by saying standard utterances. You can optionally enable additional utterances by using semantics. When you use semantics, you manually map the phrases "open", "close", "raise", and "lower" to directives.
Semantics is supported for the following interfaces only: ModeController, RangeController, and ToggleController.
Semantics object example
The following is an example of a semantics object in the discover response for a device that implements the RangeController interface. For details about each field, see the semantics object schema table following the example.
{
"semantics": {
"actionMappings": [
{
"@type": "ActionsToDirective",
"actions": ["Alexa.Actions.Close", "Alexa.Actions.Lower"],
"directive": {
"name": "SetRangeValue",
"payload": {
"rangeValue": 0
}
}
},
{
"@type": "ActionsToDirective",
"actions": ["Alexa.Actions.Open", "Alexa.Actions.Raise"],
"directive": {
"name": "SetRangeValue",
"payload": {
"rangeValue": 100
}
}
}
],
"stateMappings": [
{
"@type": "StatesToValue",
"states": ["Alexa.States.Closed"],
"value": 0
},
{
"@type": "StatesToRange",
"states": ["Alexa.States.Open"],
"range": {
"minimumValue": 1,
"maximumValue": 100
}
}
]
}
}
Semantics object schema
| Field | Description | Type | Required |
|---|---|---|---|
actionMappings |
An array of mappings between action phrases and interface directives. | Array | One of actionMappings or stateMappings is required. |
actionMappings.@type |
The type of action mapping. Currently, the only valid value is ActionsToDirective. |
String | Yes when actionMappings is included. |
actionMappings.actions |
An array of actions that are mapped to a single directive. Valid values are Alexa.Actions.Open, Alexa.Actions.Close, Alexa.Actions.Raise, and Alexa.Actions.Lower. |
Array | Yes when actionMappings is included. |
actionMappings.directive |
The directive to call for the actions. | Object | Yes when actionMappings is included. |
actionMappings.directive.name |
The name of the directive. The directive must be a directive of the capability interface that the semantics object is included in. | String | Yes when actionMappings is included. |
actionMappings.directive.payload |
The payload appropriate for the directive. Some directives do not require a payload, and the type of the payload depends on the directive. | Object | No |
stateMappings |
An array of mappings between Alexa states and your controller states. Include state mappings so that users can query the device state using the phrases Open and Closed. |
Array | One of actionMappings or stateMappings is required. |
stateMappings.@type |
The type of state mapping; one of: StatesToValue or StatesToRange. |
String | Yes when stateMappings is included. |
stateMappings.states |
An array of Alexa states that are mapped to your controller values. Valid values are Alexa.States.Open and Alexa.States.Closed. |
Array | Yes when stateMappings is included. |
stateMappings.value |
The value of your controller that corresponds to the specified Alexa states. | Value | Yes when type is StatesToValue |
stateMappings.range |
The range of values of your controller that corresponds to the specified Alexa states. | Object | Yes when type is StatesToRange |
The connections property
The connections property represents the methods that a device uses to connect to the internet and smart home hubs. The connections property contains an array of connection objects.
Connections property example
{
"connections": [
{
"type": "TCP_IP",
"macAddress": "00:11:22:AA:BB:33:44:55"
},
{
"type": "ZIGBEE",
"macAddress": "00:11:22:33:44:55"
},
{
"type": "ZWAVE",
"homeId": "<0x00000000>",
"nodeId": "<0x00>"
},
{
"type": "UNKNOWN",
"value": "00:11:22:33:44:55"
}
]
}
Connection object schema
| Field | Description | Type | Required |
|---|---|---|---|
type |
The type of connection; one of TCP_IP, ZIGBEE, ZWAVE, or UNKNOWN. |
String | Yes |
macAddress |
The unique identifier for the network interface controller (NIC). Optionally include this field when the connection type is TCP_IP or ZIGBEE. |
String | No |
homeId |
The Home ID for a Z-Wave network that the endpoint connects to. The format is 0x00000000 with UTF-8 characters. Optionally include this field when the connection type is ZWAVE. |
String | No |
nodeId |
The Node ID for the endpoint in a Z-Wave network that the endpoint connects to. The format is 0x00 with UTF-8 characters. Optionally include this field when the connection type is ZWAVE. |
String | No |
value |
The connection information for a connection when you can't identify the type of the connection more specifically. The information that you provide in this field should be stable and specific. This value can contain up to 256 alphanumeric characters, and can contain punctuation. | String | Yes when type = UNKNOWN |
The relationships object
A relationships object lists the endpoints that an endpoint is connected to. For example, a computer endpoint might be connected to a home network endpoint. For more information, see Understand Networking and Wi-Fi Skills.
Relationships object example
{
"relationships": {
"isConnectedBy": {
"endpointId": "<unique ID of the home network endpoint>"
}
}
}
Relationships object schema
| Field | Description | Type | Required |
|---|---|---|---|
isConnectedBy |
The endpoint ID of the network that this endpoint is connected to. The specified endpoint should implement Alexa.Networking.HomeNetworkController. | Object | Yes |
Directives
Discover directive
Support the Discover directive so that users find the devices associated with their account. Users can ask Alexa to discover their devices, or they can open the Alexa app and choose discover devices.
The following example shows a user utterance:
Alexa, discover my smart home devices.
Alexa, finde meine smarten geräte.
Discover directive payload details
| Field | Description | Type |
|---|---|---|
scope |
Provides authorization and identifying information for the request. | A scope object. |
Discover directive example
{
"directive": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover",
"messageId": "<message id>",
"payloadVersion": "3"
},
"payload": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
}
}
}
}
Discover response event
If you handle a Discover directive successfully, respond with an Discover.Response event. In your response, return all of the devices associated with the end-user's device cloud account, and the capabilities that your skill supports for them.
Discover response event payload details
| Field | Description | Type | Required |
|---|---|---|---|
endpoints |
The devices associated with the user's account, and the capabilities that your skill supports for them. If there are no devices associated with the user account, return an empty array for this property. The maximum number of endpoints you can return is 300. | An array of endpoint objects. | Yes |
Discover response example
The following example shows a Discover.Response message for a light that supports the Alexa.PowerController and Alexa.BrightnessController interfaces. To see example discover responses for other capabilities, see the documentation for each interface at List of Capability Interfaces and Supported Locales, and see additional Discover.Response examples.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "Sample Manufacturer",
"description": "Smart Light by Sample Manufacturer",
"friendlyName": "Living Room Light",
"additionalAttributes": {
"manufacturer" : "Sample Manufacturer",
"model" : "Sample Model",
"serialNumber": "<the serial number of the device>",
"firmwareVersion" : "<the firmware version of the device>",
"softwareVersion": "<the software version of the device>",
"customIdentifier": "<your custom identifier for the device>"
},
"displayCategories": ["LIGHT"],
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.BrightnessController",
"version": "3",
"properties": {
"supported": [
{
"name": "brightness"
}
],
"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"
}
],
"connections": [
{
"type": "TCP_IP",
"macAddress": "00:11:22:AA:BB:33:44:55"
},
{
"type": "ZIGBEE",
"macAddress": "00:11:22:33:44:55"
},
{
"type": "ZWAVE",
"homeId": "<0x00000000>",
"nodeId": "<0x00>"
},
{
"type": "UNKNOWN",
"value": "00:11:22:33:44:55"
}
],
"cookie": {
}
}
]
}
}
}
Discover directive error handling
If you can't handle a Discover directive successfully, respond with an Alexa.ErrorResponse event. Use one of the following error types as appropriate: BRIDGE_UNREACHABLE, EXPIRED_AUTHORIZATION_CREDENTIAL, INSUFFICIENT_PERMISSIONS, INTERNAL_ERROR, INVALID_AUTHORIZATION_CREDENTIAL.
AddOrUpdateReport event
You send an AddOrUpdateReport event proactively when a user adds a new endpoint to their account, or makes changes to an existing endpoint, such as renaming a scene. Send your AddOrUpdateReport message to the Alexa event gateway. You can include all the endpoints associated with the user account, or only the new or updated endpoints. You can choose based on your skill implementation.
AddOrUpdateReport event payload details
| Field | Description | Type | Required |
|---|---|---|---|
endpoints |
The devices associated with the user's account, and the capabilities that your skill supports for them. If there are no devices associated with the user account, return an empty array for this property. The maximum number of endpoints you can return is 300. | An array of endpoint objects. | Yes |
scope |
An object containing a bearer token to identify the user to Alexa. | A scope object. | Yes |
AddOrUpdateReport event example
POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "Sample Manufacturer",
"description": "Smart Light by Sample Manufacturer",
"friendlyName": "Kitchen Light",
"additionalAttributes": {
"manufacturer" : "Sample Manufacturer",
"model" : "Sample Model",
"serialNumber": "<the serial number of the device>",
"firmwareVersion" : "<the firmware version of the device>",
"softwareVersion": "<the software version of the device>",
"customIdentifier": "<your custom identifier for the device>"
},
"displayCategories": [
"LIGHT"
],
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.BrightnessController",
"version": "3",
"properties": {
"supported": [
{
"name": "brightness"
}
],
"proactivelyReported": true,
"retrievable": true
}
}
],
"connections": [
],
"cookie": {
}
}
],
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
}
}
}
}
DeleteReport event
You send a DeleteReport event proactively when a user removes an endpoint from their account.
DeleteReport event payload details
| Field | Description | Type | Required |
|---|---|---|---|
endpoints |
The endpoints to delete from the user account. | An array of endpoint ids. | Yes |
scope |
An object containing a bearer token to identify the user to Alexa. | A scope object. | Yes |
DeleteReport event example
POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "DeleteReport",
"messageId": "<message id>",
"payloadVersion": "3"
},
"payload": {
"endpoints": [
{
"endpointId": "<endpoint id 1>"
},
{
"endpointId": "<endpoint id 2>"
}
],
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
}
}
}
}
Display categories
When you provide the display category in your discovery response, your endpoint appears in the correct category in the Alexa app, with the correct iconography. This makes it easier for users to find and monitor your devices.
| Value | Description |
|---|---|
| ACTIVITY_TRIGGER | A combination of devices set to a specific state. Use activity triggers for scenes when the state changes must occur in a specific order. For example, for a scene named "watch Netflix" you might power on the TV first, and then set the input to HDMI1. |
| CAMERA | A media device with video or photo functionality. |
| COFFEE_MAKER | A coffee maker. |
| COMPUTER | A non-mobile computer, such as a desktop computer. |
| CONTACT_SENSOR | An endpoint that detects and reports changes in contact between two surfaces. |
| DOOR | A door. |
| DOORBELL | A doorbell. |
| EXTERIOR_BLIND | A window covering, such as blinds or shades, on the outside of a structure. |
| FAN | A fan. |
| GAME_CONSOLE | A game console, such as Microsoft Xbox or Nintendo Switch |
| GARAGE_DOOR | A garage door. Garage doors must implement the ModeController interface to open and close the door. |
| INTERIOR_BLIND | A window covering, such as blinds or shades, on the inside of a structure. |
| LAPTOP | A laptop or other mobile computer. |
| LIGHT | A light source or fixture. |
| MICROWAVE | A microwave oven. |
| MOBILE_PHONE | A mobile phone. |
| MOTION_SENSOR | An endpoint that detects and reports movement in an area. |
| MUSIC_SYSTEM | A network-connected music system. |
| NETWORK_HARDWARE | A network router. |
| OTHER | An endpoint that doesn't belong to one of the other categories. |
| OVEN | An oven cooking appliance. |
| PHONE | A non-mobile phone, such as landline or an IP phone. |
| SCENE_TRIGGER | A combination of devices set to a specific state. Use scene triggers for scenes when the order of the state change is not important. For example, for a scene named "bedtime" you might turn off the lights and lower the thermostat, in any order. |
| SCREEN | A projector screen. |
| SECURITY_PANEL | A security panel. |
| SMARTLOCK | An endpoint that locks. |
| SMARTPLUG | A module that is plugged into an existing electrical outlet, and then has a device plugged into it. For example, a user can plug a smart plug into an outlet, and then plug a lamp into the smart plug. A smart plug can control a variety of devices. |
| SPEAKER | A speaker or speaker system. |
| STREAMING_DEVICE | A streaming device such as Apple TV, Chromecast, or Roku. |
| SWITCH | A switch wired directly to the electrical system. A switch can control a variety of devices. |
| TABLET | A tablet computer. |
| TEMPERATURE_SENSOR | An endpoint that reports temperature, but does not control it. The temperature data of the endpoint is not shown in the Alexa app. If your endpoint also controls temperature, use THERMOSTAT instead. |
| THERMOSTAT | An endpoint that controls temperature, stand-alone air conditioners, or heaters with direct temperature control. If your endpoint senses temperature but does not control it, use TEMPERATURE_SENSOR instead. |
| TV | A television. |
| WEARABLE | A network-connected wearable device, such as an Apple Watch, Fitbit, or Samsung Gear. |
Additional Discover.Response examples
The following are some example Discover.Response events. To see example discovery responses for other capabilities, see the documentation for each interface at List of Capability Interfaces and Supported Locales.
Example for a video device
The following example shows a Discover.Response event for 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 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 an entertainment device
The following example shows a Discover.Response event for 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 guitar amp
The following example shows a Discover.Response event for a guitar amp.
{
"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 Wi-Fi router
The following example shows a Discover.Response event for 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 more information, see Understand Networking and Wi-Fi Skills.
{
"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": "text",
"value": {
"text": "Guest Network",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Guest Wi-Fi",
"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"
}
]
}
]
}
}
}
