API Migration Guide (v1 to v20160207)
The Alexa Voice Service API (v20160207) exposes an HTTP/2 endpoint and supports cloud-initiated directives, which allow you to access new features, such as Amazon Alexa app integration, media transport controls, voice-powered volume adjustment, and timers and alarms. In the following sections, we'll provide the steps you need to take to upgrade your client code to access the Alexa Voice Service API (v20160207) and ensure you're prepared for new features as they are released.
- What's New?
- Migration Steps
- 1. Review the Interaction Model
- 2. Switch to an HTTP/2 Client Library
- 3. Create and Manage an HTTP/2 Connection
- 4. Adjust for the New Message Structure
- 5. Access Alexa Voice Service API (v20160207)
Volume Controls: The Speaker interface exposes new directives and events for on-device volume control. The interface also exposes events for muting and un-muting an Alexa Built-in device. For a complete list of directives and events, see Speaker Interface.
Media Controls: New events have been added to control media playback via on-device buttons and GUI affordances. These include: PlayCommandIssued, NextCommandIssued, PreviousCommandIssued, and PauseCommandIssued. For sample messages, see PlaybackController Interface.
Timers and Alarms: With the new Alerts interface, you can enable timers and alarms on your Alexa Built-in device. For a complete list of directives and events, see Alerts Interface.
Amazon Alexa App Enhancements: Control volume, media playback (e.g. Amazon Music, Audible), as well as manage timers/alarms on your product using the Amazon Alexa app.
New Message Structure: The JSON-formatted messages that Alexa expects and returns to your client have been updated and are not backward compatible. For more information, see Step 4.
- A persistent HTTP/2 connection with AVS
- A downchannel stream, which is used to deliver cloud-initiated directives to your client
Perform the following tasks to migrate your client to the Alexa Voice Service API (v20160207):
- Review the Alexa Voice Service Interaction Model
- Switch to an HTTP/2 client library
- Create an HTTP/2 connection and establish a downchannel for cloud-initiated directives
- Implement logic to handle new message structure
- Access the Alexa Voice Service API (v20160207)
If you have any questions, comments, or encounter issues with the updated AVS API or the migration guide, please leverage the Forum and Knowledge Base where we will actively monitor and respond to developer feedback and concerns.
1. Review the Interaction Model
Expectations for how a client should behave when interacting with the Alexa Voice Service API have changed with the addition of new features (such as timers and alarms) and functionality (such as cloud-initiated directives). To avoid running into bugs and corner cases during development, we strongly recommend reviewing the Interaction Model before beginning your migration.
The Interaction Model covers:
- Interfaces, Directives and Events
- Client Interactions with the Alexa Voice Service
- The Voice Request Lifecycle
2. Switch to an HTTP/2 Client Library
In order to use the AVS API (v20160207), your device must be able to create and maintain a persistent HTTP/2 connection with AVS. The following client libraries have been reviewed and are recommended for use:
|C / C++||nghttp2|
|C / C++||curl and libcurl|
A full list of HTTP/2 implementations is available on GitHub.
3. Create and Manage an HTTP/2 Connection
After switching to an HTTP/2 client library, you'll need to be able to create and maintain a persistent HTTP/2 connection with the Alexa Voice Service and establish a downchannel stream. The downchannel allows Alexa to send cloud-initiated directives to your client. For example, when a user adjusts device volume from the Amazon Alexa App, a cloud-initiated directive is sent to your client and your client must be able to handle that directive and adjust volume on the client accordingly.
4. Adjust for the New Message Structure
Once a connection with the Alexa Voice Service is created, your client will communicate with Alexa using HTTP/2 encoded messages. Messages are composed of one or more JSON-formatted directives/events and their associated audio attachments (if required). For guidance on structuring an HTTP/2 request to AVS, see:
5. Access Alexa Voice Service API (v20160207)
AVS API (v20160207) exposes new interfaces that allow you to enable features like media transport controls, voice-powered volume adjustment, and timers and alarms.