Notifications Overview

Notification indicators inform end users that new content is available from Alexa skills and domains. When a notification is delivered, depending on what the product is capable of, the user is notified by visual and audio indicators. For example, the product may flash a yellow LED and play an audio file, at which time a user can retrieve any pending notifications by asking, "Alexa, what did I miss?" or "Alexa, what are my notifications?" (See UX Considerations for implementation specific guidance).

Flow and Delivery

When a domain or Alexa skill produces a notification, it is delivered to a cloud-based queue, and a SetIndicator directive is sent to all Alexa products associated with that user's account. This directive instructs the product(s) to immediately render visual and audio indicators that let the user know that a notification is available for retrieval.

This diagram illustrates the end-to-end flow for enablement and retrieval of notifications by the end user:

Enable: The user enables notifications for an Alexa skill or domain using the Amazon Alexa App.

Generate: The Alexa skill or domain generates notifications that are sent to a cloud-based queue.

Queue: The queue stores new (unplayed), and archived notifications.

Indicate: SetIndicator directives are sent to all AVS-enabled devices connected to the user's account. The user is notified visually and/or audibly based on two things: i) what the product supports, ii) what's included in the directive's payload.

Retrieve: The user asks, "Alexa, what are my notifications?" A Speak directive is sent to the AVS-enabled product that the request originated from, and all new notifications are played for the user. When playback is complete, a ClearIndicator directive is sent that instructs your product to clear any notifications indicators. After a notification is read, it is archived in the cloud for 24 hours and then automatically deleted. End users can also navigate between notifications, by saying "Alexa, next" or "Alexa, back", or delete notifications by saying "Alexa, delete all".Note: If Alexa informs the users that messages are available to be retrieved, a user can ask, "Alexa, what are my messages?"

How End Users Enable Notifications

End users will be able to opt-in to notifications per Alexa skill or domain using the Amazon Alexa App and be alerted when there’s new information to retrieve by a visual and audio indicator on their product. There are three ways to enable notifications:

A user can enable notifications for a specific Alexa skill when it's enabled for the first time through the Alexa Skills Store.

Alexa can guide the user to a card in the Amazon Alexa App, where the user can enable notifications for the Alexa skill or domain that's currently in use.

A user can enable or disable notifications for an Alexa skill or domain at any time using the Amazon Alexa App. Navigate to Settings > Account > Notifications and toggle notifications ON or OFF.

Note: For previously enabled Alexa skills, end users will likely encounter the request to enable notifications while speaking with an AVS-enabled product. While the user interacts with the skill, it may ask the user to opt-in to notifications, and direct the user to the Amazon Alexa App to approve the request.

Do Not Disturb

The do not disturb (DND) setting allows end users to put their devices into quiet mode. While DND is enabled, an AVS-enabled product will not receive any visual or audio indicators. However, notifications will remain accessible via voice request ("Alexa, what are my notifications?").

When a user exits DND, if there are pending notifications in their queue, AVS will send a SetIndicator directive to notify the user that content is available to be retrieved.

There are three ways to enable DND:

End users can enable or disable DND via voice.

End users can enable or disable DND via the Amazon Alexa App.

End users can set daily DND preferences via the Amazon Alexa App. For example, the user can turn off notifications every day from 5 P.M. to 7 P.M. During this time, the product will not render notifications indicators for the user.

Notification Indicators

The Notifications interface exposes two directives that instruct your product to set and clear visual and audio indicators.

SetIndicator - This directive instructs your client to render visual and audio indicators when new content is available to be retrieved. It does not include the notification content.

Additionally, your product must communicate the state of its notification indicators to AVS by including IndicatorState as a context object with applicable events.

For all products, the end user must be immediately informed when a SetIndicator directive is received, even during an ongoing interaction such as Alexa speech or media playback. This is because notifications map to the Alerts channel in the AVS Interaction Model.

The directive's payload will include two boolean values that instruct your client to persist a visual indicator and/or play an audio file. persistVisualIndicator is a global value, if true your product must continue to inform the user that notifications are available until they are retrieved by the user, the product receives a new notification with persistVisualIndicator set to false, or receives a ClearIndicator directive. playAudioIndicator lets your product know whether to audibly inform the user that a notification is available. If true, a URL is provided and must be played immediately. In the case that the audio file is unavailable, your product should play a locally stored new notification audio file as a fallback.

UX Considerations

When implementing notifications, you need to determine how best to inform your user that a notification has arrived, and how to persistently inform that user that unread notifications are available in their queue. How notifications are displayed to users depends greatly on the visual affordances that your product supports and how Alexa states are communicated. The AVS UX Design Guidelines for Notifications provides requirements and recommendations based on your product's capabilities to inform users that notifications are available to be retrieved.

Sequence Diagrams

These diagrams illustrate the typical flow of directives and events for setting and clearing notification indicators.

Scenario 1: Notifications Available

In this scenario, a notification is delivered to an AVS-enabled product.

Scenario 2: Retrieve Notifications

In this scenario, the user sees a the yellow LED pulse on their AVS-enabled product, and asks, "Alexa, what are my notifications".

Enable the Quote Maker Skill for Testing

The Quote Maker skill is a development tool that allows developers to create notifications in real-time, and trigger the sending of SetIndicator directives to all Alexa-enabled devices associated with a user account. Learn more »