Alexa Voice Service 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 functionalities 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 comprises capability interfaces that correspond to client functionality, like speech recognition, audio playback, and volume control.

AVS uses Login with Amazon (LWA) for product authorization and exposes HTTP/2 endpoints.

The current version of the Alexa Voice Service is v20160207. Read more about AVS Envelope and Capability Versioning.

What's New?

For new and updated AVS features, see blogs and documentation in the documentation changelog.

Authorization

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.

Connected Endpoints

Throughout the AVS documentation, the entity that maintains the HTTP/2 connection to Alexa is referred to as the "device", "client", or "product". In simple integrations, the device is the only entity that is the subject of end user interactions and exchanges of messages with Alexa.

AVS also enables connecting additional "endpoints" to Alexa. (Note that this is not the same use of the term as "URI endpoint" for API connections.) These connected endpoints do not maintain their own direct connections to Alexa, relying instead on the HTTP/2 device to proxy events and directives on their behalf.

From Alexa's perspective, the device and all additionally connected endpoints are all "endpoints". This is reflected in how a device reports both itself and connected endpoints in the same endpoints list in Alexa.Discovery. Where certain capability interfaces, mechanics, or fields apply only to the device maintaining the HTTP/2 connection, the documentation will make that clear. Otherwise, "endpoint" can refer to either the device or any connected endpoints.

Topology

Connected endpoints are analogous to those described by the Smart Home Skills Kit. When an endpoint is connected by a skill, it requires that the developer maintains a cloud service that is called by an AWS Lambda function. That cloud service exchanges events and directives with Alexa on behalf of any endpoints. Therefore, the developer is responsible for the connection between the cloud service and the endpoint.

When the endpoint is connected to an AVS device, the device takes the place of the cloud service, informing Alexa about the endpoint through Alexa.Discovery. When a capability interface is suitable for a connected endpoint, it will include an endpoint object in events and directives, so that when the device exchanges messages with Alexa on behalf of the endpoint, both the device and Alexa know which connected endpoint the message is about. More information is available in the Envelope Version documentation, as well as the documentation for individual capability interfaces.

It may be helpful to think of the device as a proxy for the endpoint, offering an abstraction layer to connected endpoints for the Alexa Voice Service.

Note that, unlike the cloud service in a traditional Smart Home Skills integration, the device is also itself an endpoint.

Endpoint Types and Connectivity

Endpoints may be physical or virtual. A physical endpoint might be a light bulb, thermostat, camera, or smart lock. A virtual endpoint might be a piece of software running on the device, like an installed app.

Endpoints may be separate physical entities or integrated components. For instance, a light bulb could be separate, perhaps in a ceiling lighting fixture. Alternatively, it could be integrated into the HTTP/2 device and modeled as a connected endpoint for separate control and targeting.

Alexa-defined JSON events and directives may be passed raw between the device and endpoint or translated into a different protocol, format, encoding, or signal. The only requirement is that the semantics are preserved.

If a connected endpoint is designed to be aware of Alexa specifically, it may run software to understand and use Alexa events and directives. In such cases, the HTTP/2 device can pass messages between the endpoint and Alexa without translation, over whatever connection exists between the device and the endpoint.

By contrast, if a connected endpoint is not Alexa-specific, the HTTP/2 device may need to translate the Alexa messages into the appropriate signal. For example, the device may receive a TurnOn directive for a particular light bulb endpoint. The directive might then be translated into the appropriate Zigbee signal that turns on the light bulb. This applies to virtual endpoints as well. For instance, if the device receives a directive to control an Android app that is also installed on the device, it may need to translate that directive into the appropriate Android API, then translate any response into the corresponding Alexa event.

Capability Interfaces

A capability interface ("capability", "interface", "API", or "namespace" for short) comprises a set of client functionality, like speech recognition, audio playback, and volume control.

Each capability interface defines logically grouped messages called directives and events. Alexa sends directives to the device, instructing it to take action. The device sends events to Alexa to indicate that something has occurred.

A capability interface may also define context entries, either of a generic variety or reportable state properties.

Individual messages, including context entries, include a namespace field identifying the capability interface that the event, directive, or context entry belongs to. The event, directive, or context entry is identified by the name field.

Changes

Changes to capabilities are managed through major.minor interface versions.

Assertion

Capabilities are always implemented by the device maintaining the HTTP/2 connection, but the device may implement them on behalf of connected endpoints. The documentation for each interface describes whether the device may implement it only on its own behalf or on behalf of any connected endpoints.

To assert support for a capability on its own behalf or on behalf of a connected endpoint, the device must use Alexa.Discovery (the successor to the deprecated Capabilities API).

The individual capability's documentation details how to assert support.

Interface Naming

When the Alexa Voice Service first launched, the namespace of each capability interface was a single PascalCased word describing the functionality it enabled. As the number of interfaces increased, it became necessary to create more structure in their naming to more easily group together related functionality:

  • Newer interfaces leverage hierarchical namespacing, starting with the Alexa. root.
  • Each component of the namespace between dots still uses PascalCase.
  • A namespace does not necessarily depend on implementation of its hierarchical parents. For example, the Alexa.DoNotDisturb interface does not depend on the Alexa interface. Any dependencies are indicated in the documentation for the interface.

HTTP/2

AVS exposes an HTTP/2 service and expects multipart messages encoded for HTTP/2. The following pages provide information to help you manage a connection and structure requests.

Base URLs

As of May 22nd, 2019, the default base URLs for AVS have changed. We recommend that all new and existing clients adopt these new URLs; however, the legacy base URLs will continue to be supported.

Base URLs

Region Supported Countries/Regions URL
Asia Australia, Japan, New Zealand https://alexa.fe.gateway.devices.a2z.com
Europe Austria, France, Germany, India, Italy, Spain, United Kingdom https://alexa.eu.gateway.devices.a2z.com
North America Canada, Mexico, United States https://alexa.na.gateway.devices.a2z.com

Legacy Base URLs

Region Supported Countries/Regions URL
Asia Australia, Japan, New Zealand https://avs-alexa-fe.amazon.com
Europe Austria, France, Germany, India, Italy, Spain, United Kingdom https://avs-alexa-eu.amazon.com
North America Canada, Mexico, United States https://avs-alexa-na.amazon.com

Need Help?

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.