Alexa Voice Service Overview (v20160207)
The Alexa Voice Service (AVS) allows developers to voice-enable connected products with a microphone and speaker. Once integrated, your product will have access to the built in capabilities of Alexa (like music playback, timers and alarms, package tracking, movie listings, calendar management, and more) and third-party skills developed using the Alexa Skills Kit.
AVS is comprised of interfaces that correspond to client-functionality, like speech recognition, audio playback, and volume control. Each interface contains logically grouped messages called directives and events. Directives are messages sent from the cloud instructing your client to take action. Events are messages sent from your client to the cloud notifying Alexa something has occurred.
The API uses Login with Amazon (LWA) for product authorization and exposes an HTTP/2 endpoint.
For a complete list of documentation changes and updates, visit our documentation changelog.
- AVS is now available in Mexico. Read the blog.
- The AVS Hosted Splash Screen is now available. See our announcement on the Alexa Blogs. You'll need to request the new
alexa:voice_service:preauthscope and the
alexa:allscope when using Login with Amazon (LWA) to register a new customer (and remove your existing splash screen if applicable). The AVS Hosted Splash screen will then be deployed automatically to the device that creates a LWA request in the companion app. See our reference documentation and UX guidance for more details.
- Display cards are now required for TVs, Tablets, and Set-top boxes. This change is reflected in Section 7 of the Functional Requirements.
- AVS is now available in Italy and Spain. Read the blog ».
- Alexa for Business support is now available for products with Alexa Built-In. See the Build with Alexa for Business guide and the Alexa for Business Requirements.
- We've updated the System Interface to 2.1, adding the new RevokeAuthorization directive which provides support for Alexa for Business.
- The InteractionModel interface is now available for AVS. Declaring this interface via the Capabilities API will enable Alexa Routines for your Alexa-enabled product. The PlaybackController interface has been expanded and includes two new events - ButtonCommandIssued and ToggleCommandIssued. The RenderPlayerInfo directive has been enhanced.
- Alerts interface enhanced to version 1.3, System interface enhanced to version 1.1, and Attention System documentation updated for alerts and LEDs.
- AVS is now available in France. Read the blog »
- The Supported Countries API allows a client to retrieve a list of countries or regions where Alexa is available. Learn more »
To access the AVS API your product needs to obtain a Login with Amazon (LWA) access token, which grants a product access to call the API on a customer's behalf. There are multiple ways to authorize a product:
Remote Authorization is used to authorize devices with a companion website or mobile app. Typically, remote authorization is used with headless devices, like a smart speaker.
Local Authorization is used to authorize Alexa from the AVS-enabled product. Typically, local authorization is used with Android and iOS applications.
Code Based Linking is an authorization method optimal for products with limited or no access to character input, such as a television or smart watch.
AVS expects each product to report the interfaces and interface versions that it supports on first boot (out-of-box experience), and whenever an over-the-air (OTA) update is applied. Click here to learn more about the Capabilities API and how interfaces are versioned.
The following pages provide information to help you manage a connection and structure requests.
AVS exposes an HTTP/2 service and expects multipart messages encoded for HTTP/2. The following endpoints are supported:
|Asia||Australia, Japan, New Zealand||
|Europe||Austria, France, Germany, India, Italy, Spain, United Kingdom||
|North America||Canada, United States||
Each interface is a collection of directives and events, which correspond to specific client-side functionality. Use the table below to explore:
|Alerts||The interface for setting, stopping, and deleting timers and alarms. For a conceptual overview, see Alerts Overview.|
|AudioActivityTracker||The interface that is used to inform Alexa which interface last occupied an audio channel.|
|AudioPlayer||The interface for managing and controlling audio playback that originates from an Alexa-managed queue. For a conceptual overview, see AudioPlayer Overview.|
|Bluetooth (Developer Preview)||The interface for managing connections with peer Bluetooth devices, such as smart phones and speakers.|
|EqualizerController||This interface allows a product to adjust equalizer settings using Alexa, such as decibel (dB) levels and modes.|
|InputController||This interface enables selecting and switching inputs on an Alexa-enabled product.|
|Notifications||The interface that delivers visual and audio indicators when notifications are available. For a conceptual overview, see Notifications Overview.|
|PlaybackController||The interface for navigating a playback queue via button presses or GUI affordances.|
|Settings||The interface that is used to manage the Alexa settings on your product, such as locale.|
|Speaker||The interface for controlling the volume of Alexa originated content on your product, including mute and unmute.|
|SpeechRecognizer||The core interface for the Alexa Voice Service. Each user utterance leverages the Recognize event.|
|SpeechSynthesizer||The interface that returns Alexa TTS.|
|System||The interface that is used to send Alexa information about your product.|
|TemplateRuntime||The interface for rendering visual metadata. For a conceptual overview, see Display Cards Overview.|
|VisualActivityTracker||The interface that is used to inform Alexa when content is actively displayed to an end user.|
Amazon regularly updates the Alexa Voice Service with new features, performance enhancements, and bug fixes to offer the best experience to Alexa users. These changes may result in the incremental versioning of each affected interface individually using a MAJOR.MINOR scheme. To learn more about interface versioning, see Capabilities API.
The AVS API version, currently
v20160207, guarantees that directives and events sent from Alexa conform to the same message specification.
If you have any questions, comments, or encounter issues with the AVS API, please leverage the AVS Knowledge Base and Forum where we will actively monitor and respond to developer feedback and concerns.