We recently launched Notifications for Alexa support through the AVS API. Here's a guide that walks you through everything you need to know to implement notifications on your Alexa-enabled product.

To start, the Notifications interface is comprised of two directives and a new device context. The SetIndicator directive lets your product know that there are new notifications available for your user to retrieve by rendering visual and audio indicators, such as an LED flash and an audible chime sound. It doesn’t actually deliver the content, it simply indicates that content is available. The ClearIndicator directive lets your product know that the user is up-to-date on their notifications, and instructs your device to clear any visual and audio indicators that might be rendered for the user. Finally, like all device contexts, the IndicatorState context tells AVS the current status of the notification indicator on your device.

Conceptually, your product shouldn’t care about the content of individual notifications. All your product needs to do is manage the indicator state for the user. It is AVS’ job to communicate what the proper state of that indicator should be. For a consistent Alexa experience, you'll need three notification states: a new notification has arrived; there are new notifications queued; there are no new notifications. See UX Considerations in our Notifications Overview to determine how best to display the first two states. The third is the standard idle state of your device.

When you get a SetIndicator directive, first check the playAudioIndicator field. This will let your product know whether or not there is an associated audio file that needs to be played for the user. If true, your product should download and cache the associated asset. This is a best practice, because even though asset IDs within an asset object are unique, notifications often reuse the same asset. For instance, many notifications may reuse the default notification sound. Caching the audio asset will ensure that you don’t download the same asset multiple times unnecessarily. After downloading the asset, go ahead and play it for the user. If the download fails or the asset is unavailable you should default to the locally stored audio file for notifications.

The AVS Interaction Model

Notifications map to the Alerts channel in the AVS interaction model, and as such should play above any ongoing interaction (such as Alexa speech or media playback). While your product is playing the audio asset, your product should display its “new notification arrived” state. When the audio file stops playing, transition to displaying your "new notifications queued" state.

AVS doesn't distinguish between these states – all it cares about is if the notification indicator is active. When sending the IndicatorState context to AVS, isEnabled should be true for both the "new notification arrived" and "new notifications queued" states. If playAudioIndicator is false and no audio is playing, you should skip the "new" state and transition directly to the queued notifications state.

The other boolean flag, persistVisualIndicator, controls the "queued" state. If it's true, transition to the queued state. If it's false, skip it. This flag is global, not for a specific indicator. If you had notifications queued, and you received a SetIndicator with persistVisualIndicator set to false, your product should transition directly to the "no new notifications" (i.e. the idle) state after informing the user about the latest notification. Because this state is not per-notification, when sending the IndicatorState context to AVS, you can treat the isVisualIndicatorPersisted boolean as the last SetIndicator's value for persistVisualIndicator.

A couple of rules to keep in mind while you build this feature into your AVS product:

• If you get a new SetIndicator directive with the same asset id as the notification that is currently playing sound, silently drop it. You shouldn't play the same sound twice in a row.

• However, if you get a new SetIndicator with a different assetId than the currently playing asset, queue it up to play as soon as the current one is done.

• Finally, make sure to persist the state of the indicator so it is available between reboots! AVS expects the indicator state to be sent with your first SynchronizeState so that it can update the indicator as appropriate when the user starts their device.

Learn more about the Alexa Voice Service

AVS enables developers to integrate Alexa directly into their products, bringing the convenience of voice control to any connected device. AVS provides developers with access to a suite of resources to quickly and easily build Alexa-enabled products, including APIs, hardware development kits, software development kits, and documentation. Through AVS, device makers can add a new intelligent interface to their products and offer customers access to a growing number of Alexa features, smart home integrations, and skills. Just ask, and Alexa will respond. Visit the AVS Developer Portal to get started.

Have questions? Visit us on the AVS Forum to speak with one of our experts.