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?

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.

Requirements

  • A persistent HTTP/2 connection with AVS
  • A downchannel stream, which is used to deliver cloud-initiated directives to your client

Learn more »

Migration Steps

Perform the following tasks to migrate your client to the Alexa Voice Service API (v20160207):

  1. Review the Alexa Voice Service Interaction Model
  2. Switch to an HTTP/2 client library
  3. Create an HTTP/2 connection and establish a downchannel for cloud-initiated directives
  4. Implement logic to handle new message structure
  5. Access the Alexa Voice Service API (v20160207)

Submit your questions, comments, and issues with the updated AVS API or the migration guide on Stack Overflow.

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
  • Channels

Interaction Model »

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:

Language Library
C / C++ nghttp2
C / C++ curl and libcurl
Java OkHttp
Java Netty
Java Jetty

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.

Managing an HTTP/2 Connection »

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:

Structuring an HTTP/2 Request »

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.

API Overview »

Resources

Was this page helpful?

Last updated: Nov 27, 2023