AVS Documentation Changelog

12/10/2019

New Smart Home for AVS functionality has been released, including the following documentation changes:

• Guides
  • AVS API Overview
    • Connected Endpoints
    • Interface Naming
  • AVS Envelope and Interface Versioning
  • Reportable State Properties
  • Generic Controllers
• API Reference
  • Alexa.Discovery 3.0 (as the successor to the Capabilities API)
  • Alexa 3.0
  • Alexa.PowerController 3.0
  • Alexa.ToggleController 3.0
  • Alexa.RangeController 3.0
  • Alexa.ModeController 3.0
  • Alexa.ApiGateway 1.0
  • InteractionModel 1.2

The following interfaces also have new versions, enabling new functionality:

• SpeechSynthesizer 1.3
  • support for user interruption of TTS
  • support for cloud interruption of TTS
  • support for captions of TTS
• AudioPlayer 1.4
  • support for attenuation versus pausing of interrupted playback
  • support for captions of spoken content
  • support for device-reported player software information and playback telemetry, enabling enhanced audio streams and new music service providers
  • additional metadata about the initiation of music playback

The Alexa Voice Service (AVS) Device SDK documentation moved from the GitHub repository, to the developer portal. The following documentation has been added:.

• Get started
  • Overview
  • Release notes
  • Dependencies
  • Authorization
• Quick Start Guides
  • Android
  • iOS
  • Generic Linux
  • MacOS
  • Raspberry Pi
  • Ubuntu Linux
  • Windows 64
• Configurations
  • Cmake Parameters
  • Endpoints
  • Features
  • Interfaces
• Optimizations
  • Build Libcurl with TLSand Nghttp2
  • Optimize Libcurl
  • Runtime Configuration for CA Certificates
  • Update the SDK
• Troubleshooting
  • Unit and Integration Tests
  • Common Issues
  • Report an issue

11/14/2019

New API documentation has been added to support the Alexa Presentation Language (APL), which extends the AVS to enable multi-modal experiences on Alexa Built-In devices. See Alexa Multi-Modal API Overview for a summary.

Section 7 of the AVS Functional Requirements has been updated to include devices using APL to render Alexa visual responses.

9/25/2019

The AVS Settings paradigm has changed in favor of individually named messages for each setting. The Per-Interface Settings page describes the new approach baed on whether changes are initiated by the cloud or by the device, as well as validating whether settings are synchronized. The changed paradigm includes being able to report a state and values for settings like locale and time zone.

The System Interface page has been updated to include version 2.0, and the changes are listed on the page. As part of this change, the Settings interface has been deprecated. In addition, the Alexa.ApiGateway interface replaces the SetEndpoint functionality.

In coordination with the Settings paradigm described above, there is an additional settings-related functional requirement 8.3 that focus on allowing the customer to choose their preferred languages.

In addition, Alexa has a new Multilingual Mode which, if you use it in your product, must be supported in the companion app settings. Using multilingual mode, Alexa is able to understand customer utterances in multiple languages and reply in the language the customer is currently using. Details can be found on the updated System Interface page.

9/13/2019

The UX Design section was updated to include these changes:

• The guidance and best practices for designing smart speaker products have been updated in UX Design for Speakers, Soundbars, and AVRs. The changes bring the recommendations on setup, buttons, and attention system into alignment with recent updates to UX guidance in those areas. Additional references have also been added for device makers to discover more details and product design assistance.
• The Audio Hardware Configurations page has also been aligned to recent changes in UX design recommendations.
• The code-based linking (CBL) images (including redlines) have been replaced to include updated terminology on the Setup and Authentication page.
• The Multicolor LEDs table in the Calling, Messaging, and Announcements page was corrected to remove the mention of an audio cue for Active Calls.
• The Attention System page now includes references to Named Timers.

7/12/2019

The Attention System UX page now includes the following guidance:

• Text displaying the attention state should not be personalized or presented in the first person.
• Touch-initiated products must use the Listening start and end audio cues.
• Linear voice chrome is preferred over circular voice chrome for devices with screens.
• Circular voice chrome examples have been added.

5/22/2019

The default base URLs for Alexa Voice Service connections have changed. 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, India	https://alexa.fe.gateway.devices.a2z.com
Europe	Austria, France, Germany, 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, India	https://avs-alexa-fe.amazon.com
Europe	Austria, France, Germany, Italy, Spain, United Kingdom	https://avs-alexa-eu.amazon.com
North America	Canada, Mexico, United States	https://avs-alexa-na.amazon.com

5/10/2019

A new page has been added presenting attention system design guidance for calling and drop-in, messaging, and announcements on AVS products which include those functions. The Attention System - Calling, Messaging, and Announcements page includes behavior descriptions as well as visual and sound cues.

5/3/2019

To help tune products for Echo Spatial Perception, and to give more constant noise suppression performance across products, we have added AVS Functional Requirement 2.5: "The microphones used for Alexa interactions on your product SHALL have +/- 1 dB sensitivity matching."

4/16/2019

• A new design guidance page has been added describing the behavior, location, and appearance of buttons for Alexa Built-in devices.
• A new design guidance page has been added to suggest how Alexa Built-in devices should handle interrupt behavior and prioritizing customer interactions.
• The AVS Functional Requirements have been updated to reflect the new button and interrupt guidance:
  • Added requirements relating to the Action button (1.3) and Alerts (5).
  • Clarified requirements for wake word and interrupt guidance in voice-initiated products (2) and touch-initiated product (3.4).
• In the AVS UX Logo and Brand Usage page, the color called "black" was actually "squid ink". The color codes supplied were correct, but were referred to incorrectly. The color name has been updated.

3/21/2019

Alexa is now available in Canadian French. fr-CA is now a supported locale for Settings.SettingsUpdated events.

2/1/2019

• Clarified the UX guidance for visual and sound cues when Do Not Disturb is toggled on and off. In addition, DND information was added to the Multicolor Linear and Multicolor Single tabs of the LED example table.
• The recommended UX behavior of the Reminder Short response in the LED example table was expanded to cover what should happen when the device is unable to play a speech response. In addition, the sound cue was added to the table and can be stored on device as a fall-back.

12/19/2018

• Opus is now a supported format for captured audio. Review the specification under the Recognize event.
• DoNotDisturb interface is now available for AVS. Declaring this interface via the Capabilities API will enable users to block incoming notifications, announcements and calls for your Alexa Built-in product. This interface contains one new directive, SetDoNotDisturb, and two events, ReportDoNotDisturb and DoNotDisturbChangedEvent.
• Do Not Disturb UX guidance has been added to the AVS UX Attention System document, including information on enabling/disabling behavior and visual and sound cues.
• Do Not Disturb LED animation has been added to the AVS Resource Files for all arrays.

11/07/2018

• 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:preauth scope and the alexa:all scope 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.

10/24/2018

• The System Interface has been upgraded to v2.1, which includes the new RevokeAuthorization directive.
• Alexa for Business is now available:
  • Build with Alexa for Business.
  • Alexa for Business Functional Requirements.
• AVS is now available in Italy and Spain.
  • Read the blog or view the reference doc.
• AVS is now available in Italy and Spain.
  • Read the blog or view the reference doc.

10/22/2018

• We have updated the Alexa attention state colors to more closely align with Amazon devices in order to provide customers with as much consistency in the Alexa experience as we can. Specifically, we have updated Screen Hex values for Red, Green, Purple, and Orange. The LED Hex values remain the same.

10/12/2018

• We've updated the font resources in the Developer Portal for you to use according to the UX design guidelines. We're updating Amazon Ember to Amazon Ember Display, and we're adding Bookerly (which is used mainly for Things to Try text) and Noto Sans CJK for Chinese, Japanese, and Korean language support.

8/28/2018

• The InteractionModel interface is now available for AVS. This enables you to support the Alexa Routines feature in your products. To enable Alexa Routines, you must declare the InteractionModel 1.0 in the Capabilities API.
• We have updated the Interaction Model voice request lifecycle to account for the addition of the optional InteractionModel interface.
• We have updated the TemplateRuntime interface. The RenderPlayerInfo directive has been expanded to support Audible and Flash Briefing, and the controls list includes new media control events. TemplateRuntime remains at version 1.0 in this release.
• The PlaybackController interface has been upgraded to v1.1, and includes two new events - ButtonCommandIssued and ToggleCommandIssued. These events enable your product to support new controls (skip forward, skip backward, shuffle, repeat, loop, thumbs up, and thumbs down) for media playback.
• We have updated Display Card UX guidance (Tablet and TV) for playbackController 1.1 and modified the example images. We added a new resource link section at the bottom of each page
• We have included a new UX guidance page for low-resolution displays.

8/14/2018

• We have updated the AVS Security Requirements. Commercially distributed devices must meet the minimum security requirements outlined in this document.
• Updated the Alexa Voice Service Overview to include complete list of available interfaces.

8/2/2018

• We have added links to download the LED animation and Ember font resources.

Find the Ember font files to use for your text display on the Amazon Developer Portal under the Resources tab.

7/26/2018

• AVS Display Cards for Tablets and AVS Display Cards for TVs now include improved design guidance. The URLs to the associated asset resources have also changed to simplify file names.

7/23/2018

• The EqualizerController interface allows a product to adjust equalizer settings using Alexa, such as decibel (dB) levels and modes.
• The InputController interface enables selecting and switching inputs on an Alexa Built-in product.

7/9/2018

• The ReportSoftwareInfo directive is available only in v1.1 of the System interface. Documentation has been updated to reflect this change.
• Alerts interface has been enhanced to v1.3, which allows for independent volume control of alerts via the Amazon Alexa app, and introduces the ability to delete multiple alerts.
• Updated the Alerts Overview for v1.3.
• Alerts guidance and the Alexa Attention State Colors have been updated.

6/12/2018

• Updated AVS UX Attention System.

6/11/2018

• Added Alexa Auto Marketing and Branding Guidelines to the developer portal.
• Added Marketing on Amazon.com to the left nav.

6/5/2018

• AVS is now available in France.
  • Read the blog or view the reference docs.
  • French translations of the standard setup strings are available at Setup and Authentication
• Updated Alexa brand color in UX Logo and Brand Usage

5/23/2018

• Released the first batch of AVS tutorials. Learn more »

5/8/2018

• Released the Supported Countries API, which allows a client to retrieve a list of countries or regions where Alexa is available.
  • Supported Countries API

4/17/2018

• Released the Capabilities API, which allows products to individually declare the interfaces and interface versions that they support.
  • Capabilities API
  • Blog: Publishing Your Capabilities to Alexa
• Versioned each interface. Where applicable, a selector is available to navigate between versions.
  • Alerts
  • SpeechRecognizer
• Released Focus Management, a feature that improves the accuracy of responses from Alexa, specifically, when a user makes an ambiguous request.
  • Focus Management Overview
  • AudioActivityTracker
  • VisualActivityTracker

4/2/2018

• Published the Update Certificate Authorities guide to prepare developers to support Amazon Trust Services (ATS) by June 15, 2018.
• Updated the Marketing Approval Process in Amazon Alexa Brand External with contact information for Alexa Auto.

3/29/2018

• Clarifying edits have been made to the Interaction Model to emphasize that dialogRequestIds must be unique to each Recognize event, and must not be reused during a session. See Voice Request Lifecycle.

3/27/2018

• The following pages on the Japanese Developer Portal have been updated:
  • API Overview | Alexa Voice Serviceの概要(v20160207)
  • Code Based Linking | 他のデバイスやプラットフォームでのコードベースのリンク(CBL)
  • Display Cards Tablets | タブレット向けAVS表示カード
  • Display Cards TV | TV向けAVS表示カード
  • Enable Cloud Based Wake Word Verification | クラウドベースのウェイクワード検証の有効化
  • Functional Requirements | AVS製品の機能要件
  • Prepare for Internationalization | 各国化対応の準備
  • SpeechRecognizer Interface | SpeechRecognizerインターフェース
  • Streaming Requirements for Cloud Based Wake Word Verification | クラウドベースのウェイクワード検証の要件

2/12/2018

• NEW StreamingStarted and StreamingEnded events were added to the Bluetooth interface. These events are sent to notify Alexa of streaming state changes. See Manage Bluetooth Streaming State for details.
• Updated parameter descriptions for the Recognize event and ExpectSpeech directive.

1/31/2018

• AVS is now available in Australia and New Zealand. Read more »

1/30/2018

• AVS is introducing two changes that may require updates to your product’s client code: 1) Cloud-based wake word verification is now required for all voice-initiated products; 2) the initiator type in ExpectSpeech directives has changed from a string to an object. Read more »

12/6/2017

Additional guidance added to documentation for the SetAlert directive and AlertStopped event.
``

11/9/2017

• NEW Documentation is now available for Code-Based Linking.

11/8/2017

• NEW Developer documentation is now available in Japanese. Language can be toggled within the Developer portal, bottom of page.

10/6/2017

• NEW Bluetooth documentation released in Developer Preview. See Bluetooth Interface.

8/28/2017

• NEW AVS Security Requirements.

8/3/2017

• Updated Alerts documentation updated to reflect support of Named Timers and Reminders. See Alerts interface.

7/7/2017

• New Notifications documentation released.
• Updated Functional Requirements updated for Notifications.

6/21/2017

• NEW - How to Enable Named Timers and Reminders
• Updated - Alerts Interface
• NEW Display Cards Overview
• NEW TemplateRuntime Inteface
• NEW Display Card Guidelines for TVs
• NEW Display Card Guidelines for Tablets
• Updated UX Design Guidelines.html
  • The UX Design Overview have been updated with display card specifications.
• Updated Functional Requirements for AVS
  • The Functional Requirements for AVS has been updated with requirements and recommendations that you should take into consideration when building the feature into your product.

05/15/2017

• New - Enable Cloud-Based Wake Word Verification
• New - Streaming Requirements for Cloud-Based Wake Word Verification
• Updated - SpeechRecognizer Interface
  • The Recognize event and ExpectSpeech directive have been updated to support cloud-based wake word verification.
• Updated - PlaybackController Interface
  • Sample messages have been updated to include SpeechRecognizer.RecognizerState in the context object. This is only required for clients that use cloud-based wake word verification.
• Updated - System Interface
  • Sample messages have been updated to include SpeechRecognizer.RecognizerState in the context object. This is only required for clients that use cloud-based wake word verification.
• Updated - Context
  • SpeechRecognizer.RecognizerState sample message added.
• Updated - Managing an HTTP/2 Connection
  • Sample messages have been updated to include SpeechRecognizer.RecognizerState in the context object. This is only required for clients that use cloud-based wake word verification.

9/15/2017

• Branding and Marketing Guidelines updated to include Out-of-Box Experience (OOBE), packaging, and web presence recommendations.

1/30/2017

• LWA Mobile SDK: The Login with Amazon (LWA) Mobile SDKs for Android and iOS were updated in November 2016. If you are using a companion app or authorizing directly from a product, you’ll need to integrate the latest version of the LWA Mobile SDK to support AVS’s international features. See Prepare for Internationalization.
• EU Endpoint: A new AVS endpoint for Europe is available that provides customers in the UK and Germany with access to their personal data and country or region specific content.
• SetEndpoint Directive: The SetEndpoint directive instructs your client to switch endpoints if a user’s settings are not supported on the endpoint your product is connected to.
• Settings Interface: The new SettingsUpdated event allows a client to adjust Alexa settings, such as locale, using on-product controls or a companion app.

10/6/2016

• Automatic Speech Recognition (ASR) Profiles - AVS provides a choice of three ASR Profiles tuned for different products, form factors, acoustic environments and use cases: CLOSE_TALK, NEAR_FIELD, and FAR_FIELD. For additional information, see Audio Hardware Configurations.
• Cloud endpointing is now supported, and allows Alexa to determine when a user has stopped speaking. Previously only client endpointing was supported. This new feature is enabled by default when using the NEAR_FIELD or FAR_FIELD ASR Profiles. To learn more, see the Recognize event.
• The StopCapture directive is designed for cloud endpointing. When Alexa determines that a user has stopped speaking, the StopCapture is sent from Alexa to your client instructing it to stop listening.

3/22/2016

• The Alexa Voice Service (AVS) API was versioned from v1 to v20160207. This release introduces the following capabilities:
• Volume Control: Ability to adjust and mute/unmute volume on your product using voice or buttons. For more information, see Speaker interface.
• Media Control: Ability to control media playback (e.g. play/pause) on your product using voice or buttons. For more information, see AudioPlayer interface and PlaybackController interface.
• Timers and Alarms: Ability to create and manage timers/alarms on your product using voice. For more information, 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.