Home > Alexa > Alexa Voice Service

Alexa Voice Service Functional Design Guide

Best practices for integrating Alexa into your product

Overview

Customers who purchase a product with Amazon Alexa expect a familiar experience. This document provides functional and design requirements and recommendations to help you meet customer expectations and avoid issues as you develop, prototype, and prepare your product with Alexa enabled for commercial release.

The following terms are used consistently throughout this document to signify requirements and recommendations:

  • SHALL: Items preceded by SHALL are required for all commercial product releases.
  • SHOULD: Items preceded by SHOULD are recommended for all commercial product releases and significantly improve the Alexa customer experience.

The following terms are used consistently throughout this document to describe Alexa features and concepts

  • Voice-initiated: Products activated by customer speech for a hands-free experience. They can also be activated by a customer’s touch.
  • Touch-initiated: Products activated by a customer’s physical action on the product. These products do not support voice-initiated interactions.
  • Tap-to-talk: Touch-initiated products activated by the customer pushing and releasing a button before speaking.
  • Hold-to-talk: Touch-initiated products activated by the customer holding down a button while speaking.
  • Attention states: The parts of an Alexa conversation flow, including Listening and Thinking.
  • Physical control: A hardware or GUI control that is used to wake Alexa or adjust the product’s settings.
  • Visual cues: Visual cues are LEDs or GUI elements that provide feedback to the customer on Alexa’s state.
  • Audio cues: Audio cues are sounds that provide feedback to the customer on Alexa’s transitions between attention states.
  • Multi-turn: A multi-turn interaction refers to situations where Alexa requests additional spoken information from the customer to complete an interaction. Multi-turn situations are initiated when your product receives an ExpectSpeech Directive from AVS.

Living Document

We look to the AVS community to innovate and create new Alexa-enabled experiences. As we learn from you and we introduce new features and functionality, this document will be improved and updated.

The current guidelines were published on December 8, 2016.

1. Core Requirements and Recommendations

The following requirements and recommendations are applicable to all products with Alexa enabled.

1.1. Your product SHALL be capable of audio input (i.e. capturing customer speech via one or more microphones) and streaming captured speech to the cloud per the specs provided in the SpeechRecognizer Interface.

1.2. Your product SHALL be capable of audio output (e.g. speaker, headphones, line out, or Bluetooth).

1.2.1 Your product SHOULD provide physical controls for adjusting volume.

1.3. Your product SHALL provide a physical control to manually initiate an interaction with Alexa.

1.3.1. Your product SHALL enable customers to interrupt an Alexa-initiated output (e.g. media playback or Alexa voice response) using voice or a physical control. The physical control that satisfies 1.3 SHALL also be used to interrupt an Alexa-initiated output.

1.3.2. If you choose to implement a GUI control to satisfy 1.3, it SHALL always be accessible from your user interface and cannot be hidden at any time.

1.3.4. The physical control SHOULD only have the single purpose of initiating Alexa interactions.

1.4. Your product SHALL clearly convey core Alexa attention states to the customer. See the AVS UX Design Guidelines for further information about the Alexa attention states.

1.4.1. Your product SHALL provide audio cues to indicate when your product begins and ends listening.

1.4.2. Your product SHOULD include visual cues to indicate the Alexa attention states Listening, Active Listening, Thinking and Speaking with speech to the customer.

1.4.3. If your product uses visual cues to convey Alexa attention states, your product SHALL indicate all attention states as defined in the AVS UX Design Guidelines.

1.5. Your product SHALL support multi-turn interactions with Alexa.

1.5.1. Your product SHALL use the same methods for conveying the start and end of the Listening attention state for all multi-turn interactions as for the initial interaction.

1.6. Your product SHALL support silencing notifications/alerts, adjusting volume, and stopping media when internet connectivity is unavailable.

2. Voice-Initiated Products

The following guidelines are specific to voice-initiated products and extend the Core Requirements and Recommendations for those products.

2.1. Your product SHALL only use Alexa as the wake word.

2.2. Your product SHALL automatically activate its microphones without waiting for the wake word in multi-turn interactions. See also 1.5.

2.3. Your product SHALL provide an always-available control to disable its microphones, and SHALL use visual cues clearly and continually to convey to the customer that the Alexa Microphone Off attention state is active.

2.3.1. You SHALL provide audio cues to indicate when the Microphone Off attention state is activated and deactivated.

2.4. Your product SHALL support enabling/disabling microphones when internet connectivity is unavailable. See also 1.6.

3. Touch-Initiated Products

The following guidelines are specific to touch-initiated products and extend the Core Requirements and Recommendations for those products. Unless noted, the guidelines apply to both tap-to-talk and hold-to-talk products.

3.1. Your product SHALL NOT require the use of a wake word as part of the customer utterance.

3.2. Your product’s microphones SHALL be disabled until customer initiates an Alexa interaction.

3.3. Your product SHALL automatically activate its microphones without waiting for a touch interaction in multi-turn situations. The sole exception is hold-to-talk devices where the microphones are only activated when the customer holds down a physical control. See also 1.5.

3.4. Your product SHALL use audio cues to indicate the start and end of the Listening attention state.

4. Media Services

The following guidelines apply to all products that support media services such as Amazon Music, TuneIn, iHeartRadio, Audible and Flash Briefing. For additional information on handling competing audio outputs, please review the AVS Interaction Model. All of the below guidelines apply to both voice-initiated and touch-initiated products.

4.1. Your product SHALL pause or attenuate (lower speaker volume) audio output when a customer initiates an Alexa interaction during media playback.

4.1.1. Your product SHALL pause Audible content playback when interrupted by a customer.

4.1.2. If your product pauses media because of a customer interruption, it SHOULD resume playback automatically.

4.2. Your product SHALL allow customers to resume paused media using a voice request or a physical control.

4.3. Your product SHOULD sufficiently buffer media so that short interruptions in internet connectivity do not disrupt playback.

5. Notifications/Alerts

The following guidelines apply to delivering and controlling notifications and alerts, and extend 1.6. of the Core Requirements and Recommendations.

5.1. Your product SHALL deliver previously scheduled notifications/alerts to customers, such as timers or alarms, when internet connectivity is unavailable.

5.1.1 If notifications/alerts are delivered while internet connectivity is unavailable, your product SHALL send the appropriate events for the delivered notifications/alerts to Alexa when an internet connection is reestablished. For additional information, see Understanding Alerts.

5.2. Your product SHOULD support the use of physical controls to silence sounding notifications/alerts.

5.3. Your product SHOULD support independent volume control for notifications/alerts. When a customer adjusts a product’s volume for media output, it SHOULD NOT affect the volume for notifications/alerts.

6. Setup and Authentication

The Alexa setup process communicates the value of Alexa and helps customers connect your product to their Amazon account. Ideally, the Alexa setup flow should be incorporated into the setup or first run experience on your product. See the AVS UX Design Guidelines for more branding and style information for the Alexa setup and authentication experience.

6.1. Your product SHALL use Login With Amazon (LWA) to authenticate the customer. See the Authorization section in the AVS API Overview for additional information.

6.2. Your product SHALL have an Alexa setup/sign in experience that follows the Setup and Authentication guidelines in the AVS UX Design Guidelines.

6.2.1. Your product SHALL have a Splash Screen before the customer enters the Login With Amazon authentication flow. Your Splash Screen SHALL include the required elements as defined in the AVS UX Design Guidelines.

6.2.2. Your product SHALL have a Things to Try screen after the customer exits the Login With Amazon authentication flow. Your Things To Try screen SHALL include the required elements as defined in the AVS UX Design Guidelines.

6.3. Your product SHALL support logout by the customer.

6.4. You SHOULD include information on Alexa setup and use in your product’s instructional materials.

Resources