Capabilities API
Alexa.Discovery must be used for all new AVS integrations, and no capability support should be configured in the Developer Console. Previously registered products can use the Developer Console to assert capabilities only as a mechanism to correct bugs until all individual devices can adopt Alexa.Discovery.
When your device begins making successful calls to Alexa.Discovery, Alexa will no longer assume support for required interfaces, such as SpeechRecognizer or SpeechSynthesizer. Additionally, for the individual device using Alexa.Discovery, no capabilities set in the AVS Developer Console will apply.
The Capabilities API provides the mechanism for declaring support for new Alexa interfaces and versions at the individual device level. This allows each unit of your product to take advantage of new Alexa features as soon as its software is updated, rather than waiting for enough devices to have their software updated and then asserting support for Alexa interface changes at the overall product level in the AVS Developer Console.
Use Cases
These are the primary use cases for the Capabilities API:
- To inform Alexa which interfaces and interface versions that the device supports during its out-of-box-experience (OOBE). This call must be made after an access token has been obtained and before a connection with the Alexa Voice Service (AVS) is established.
- To inform Alexa which interfaces and interface versions that your device supports following an over-the-air (OTA) or other software update. This ensures that a device will only receive directives and message payloads associated with the interface versions published to Alexa.
In both cases, the Capabilities API call is required to provide a complete list of all capability interfaces your device implements: For every message your device processes (including events, directives, and context
entries), the value of the namespace
field in the header
objects must appear in the list of your device's capabilities.
Frequency
The Capabilities API should be called as infrequently as possible, with the understanding that Alexa should have awareness of your device's supported interfaces and interface versions.
Use these guidelines to determine when it is appropriate to declare the complete list of interfaces that your device supports:
- Every time that your device acquires a new access token due to an association with a new or different Amazon customer account, the capabilities associated with your device are cleared and the Capabilities API must be called. This should be considered an OOBE.
- If your device has persistent storage, is aware of software updates, and can track previously declared interfaces and interface versions, the Capabilities API should only be called when support for interfaces is added, removed, or changed.
- If your device has limited storage and is not aware of previously declared interfaces and interface versions, the Capabilities API should be called on startup following a software update.
- If your device does not have persistent storage, the Capabilities API should be called on startup.
Following a successful call, your device will receive an HTTP 204 No Content
response. If an HTTP 500 Internal Service Error
response is returned, then your device should retry after 1 second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until an HTTP 204
response is received.
Versioning
See the Versioning documentation for more information.
When new directives and events are added to or removed from an interface, or when message payloads are adjusted, impacted interfaces will be versioned independently using a MAJOR.MINOR scheme.
Changes from version to version are cataloged on each interface page when introduced, and recorded in the documentation changelog.
Minor Version
For backward compatible, non-breaking changes, the MINOR number for an interface version is increased. A minor version change generally occurs when:
- new directives and events are added to an interface
- parameters are added to the message payload of a directive or event
For example, the Alerts interface was incremented from 1.0 to 1.1 to support Named Timers and Reminders. This change introduced new payload parameters to the SetAlert
directive for enhanced functionality, however, it remained backward compatible and didn't break existing clients.
Major Version
When breaking changes are introduced, the MAJOR number for an interface version is increased. Here are a few examples of what would result in a major version change:
- existing directives and events are removed from an interface
- the data type for an existing parameter is changed
- parameters are removed from the message payload of an existing directive or event
For example, the SpeechRecognizer interface was incremented from 1.0 to 2.0 when the initiator
parameter's type was changed from a string to an object in ExpectSpeech
directives.
Legacy Devices
Adoption of the Capabilities API is required to integrate support for new and changed Alexa interfaces into your device.
However, if you are no longer updating your product's software, implementing the Capabilities API is unnecessary. In that case, or if you intend to but have not yet implemented the Capabilities API, Alexa will infer support for specific interfaces and versions based on the following logic:
- Required interfaces will be assumed to be at version 1.0:
- Alerts 1.0
- AudioPlayer 1.0
- Notifications 1.0
- PlaybackController 1.0
- Settings 1.0
- Speaker 1.0
- SpeechRecognizer 1.0
- SpeechSynthesizer 1.0
- System 1.0
- Capabilities set for all units of your product through the AVS Developer Console will imply the following versions:
- Named Timers and Reminders: Alerts 1.3 (Note that this will override the default assumption of Alerts 1.0 as a required interface.)
- Bluetooth: Bluetooth 1.0
- Display Cards: TemplateRuntime 1.0
Request
Method | PUT |
URI | https://api.amazonalexa.com/v1/devices/@self/capabilities |
Data Format | JSON |
Header Parameters
Parameter | Description | Type | Required |
---|---|---|---|
Content-Type | Specifies the format of the message returned by Alexa. Accepted value: application/json |
string | Yes |
Content-Length | This indicates the size of the entity-body, in bytes, sent to Alexa. | integer | Yes |
x-amz-access-token | This is the access token obtained from Login with Amazon (LWA) during authorization. See Authorization for a complete list of authorization options for AVS. | string | Yes |
Sample Request Headers
Content-Type: application/json Content-Length: {{INTEGER}} x-amz-access-token: {{LWA_ACCESS_TOKEN}}
Body Parameters
Parameter | Description | Type | Required |
---|---|---|---|
envelopeVersion | This value informs Alexa which version of AVS's message format and interaction model your device uses. The format's specifications are implicit in the API documentation, controlling the structure outside of any individual interface's payload objects. All events and directives must conform to the declared version.Accepted value: 20160207 |
string | Yes |
capabilities | This is a list of objects, each representing a capability interface. All interfaces that your device supports must be included in this list. The values of each top-level field inside these objects are defined by the interface. | list | Yes |
capabilities[i].type | Accepted value:AlexaInterface |
string | Yes |
capabilities[i].interface | Specifies an Alexa interface. Accepted values: All interfaces listed in the Alexa Voice Service Overview. |
string | Yes |
capabilities[i].version | The version of the interface that your device supports. Important: Each interface is versioned independently, and the contents of message payloads vary from one version to the next. | string | Yes |
capabilities[i].configurations | If the version of the interface defines any optional interface-specific configurations, this object informs Alexa of how the interface is implemented in device software. The schema for configurations belongs to the interface spec. |
object | No |
Sample Request Body
capabilities
list.{ "envelopeVersion": "20160207", "capabilities": [ { "type": "AlexaInterface", "interface": "Alerts", "version": "1.1" }, { "type": "AlexaInterface", "interface": "AudioActivityTracker", "version": "1.0" }, { "type": "AlexaInterface", "interface": "AudioPlayer", "version": "1.0" }, { "type": "AlexaInterface", "interface": "Bluetooth", "version": "1.0" }, { "type": "AlexaInterface", "interface": "EqaulizerController", "version": "1.0" }, { "type": "AlexaInterface", "interface": "Alexa.InputController", "version": "3.0" }, { "type": "AlexaInterface", "interface": "InteractionModel", "version": "1.0" }, { "type": "AlexaInterface", "interface": "Notifications", "version": "1.0" }, { "type": "AlexaInterface", "interface": "PlaybackController", "version": "1.1" }, { "type": "AlexaInterface", "interface": "Settings", "version": "1.0" }, { "type": "AlexaInterface", "interface": "Speaker", "version": "1.0" }, { "type": "AlexaInterface", "interface": "SpeechRecognizer", "version": "2.0" }, { "type": "AlexaInterface", "interface": "SpeechSynthesizer", "version": "1.0" }, { "type": "AlexaInterface", "interface": "System", "version": "1.2" }, { "type": "AlexaInterface", "interface": "TemplateRuntime", "version": "1.0" }, { "type": "AlexaInterface", "interface": "VisualActivityTracker", "version": "1.0" } ... // This should be a complete list of // interfaces that your device supports. // All required interfaces must be declared. ] }
Response
Alexa will respond to all requests with an HTTP status code.
Status Codes
HTTP Status Code | Message | Description |
---|---|---|
204 | No Content | The request was successfully processed. |
400 | Bad Request | There was an issue with the payload. A 400 error will return a JSON document that includes an error object with details describing the error. |
403 | Forbidden | Authentication failed. |
500 | Internal Service Error | An unknown problem was encountered when processing or storing the capabilities. Retry after 1 second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until an HTTP 204 response is received. |
Error Messages
A 400 error will return a JSON document that includes a single error object with details describing the error.
Error Message | Description |
---|---|
"Invalid envelope version" | An invalid parameter was published for envelopeVersion . |
"Missing capabilities" | The capabilities list is missing. |
"{field} cannot be null or empty" | The type , interface , and/or version declared are invalid. |
"Unknown interface {name}, type {x}, version {number} combination" | An invalid combination of type , interface , and/or version were provided. |
400 Error Structure
{ "error": { "message": "{{STRING}}" } }