About Alexa Voice Service (AVS) Alerts
The Alexa Voice Service (AVS) includes an Alerts feature that enables users to set and manage timers, alarms, and reminders. Read on to learn about the concepts and use cases for implementing Alerts on an Alexa Built-in device.
For detailed information about the Alerts interface see the Alerts Interface API reference page.
The following diagram illustrates state changes driven by the Alerts component. Boxes represent Alerts states and connectors represent transitions:
Alerts supports the following states:
- Idle – Before an already set alert plays, the Alerts component should be in the idle state. Alerts should return to an idle state after an alert ends. An alert ends as the result of user speech, pressing a physical button, or interacting with a GUI element.
- Foreground alert – When a user sets an alert on a device, Alerts should transition from the idle state to the foreground alert state as the alert starts, and the device sends the
AlertStartedevent to AVS.
- When the Alerts channel is in the foreground, the Dialog channel should be inactive. For more details about channels and channel prioritization, see Interaction Model.
- When a user stops an alert through an utterance, button press, or GUI element interaction, the Alerts component should transition from the foreground alert state to the idle state.
- If the Dialog channel becomes active as an alert is going off, your Alerts component should transition from the foreground alert state to the background alert state as long as the Dialog channel is active. When the Dialog channel becomes inactive, the Alerts component should return to the foreground alert state until the alert completes.
- Background alert – The Alerts component should transition to the background alert state when the Dialog channel is active. For more details about channels and channel prioritization, see Interaction Model.
Manage alerts locally
Adhere to the following requirements for locally managing clock and alert behavior on a device:
- Local clock management – Managing your device clock ensures that alerts work as designed. AVS sends all directives in UTC time. When a user instructs a device, "Set a timer for three minutes," AVS takes into account the user time zone and determines the correct UTC time that corresponds to the request. If a user adjusted the device locale, alerts might not function properly. To prevent synching issues, the Network Time Protocol (NTP) for clock synchronization.
- Loss of internet connectivity – Your device must have the ability to act on existing set alerts if the device loses internet connectivity. For example, if a user sets an alarm for 7:30 AM before going to sleep, and the device loses internet connectivity during the night, the device must have the ability to still play the alert at 7:30 AM.
Power outages or device reboots – In the event of a power outage or reboot, the device must have the ability to persist and restore existing alerts from local storage. The device isn't required to send any events notifying Alexa that the alerts were reset.
If a user interrupts a scheduled alert by powering off or rebooting a device, adhere to the following rules:
- For alerts scheduled to go off in the previous 30 minutes, the device must trigger the alerts and send all corresponding events.
- If more than 30 minutes have elapsed from the scheduled delivery time for an alert, discard the alerts, and have your device send an
AlertStoppedevent to AVS for each discarded alert.
Amazon Alexa app support
In version 1.3 and later, the Alerts interface supports the ability of users to adjust alarm and timer settings through the Amazon Alexa app.
The following table lists the user actions and the lifecycle events that the device sends to AVS.
DeleteAlertFailedevents in response to a
DeleteAlertdirective. Don't send these events for actions taken locally.
|User Action||Server Behavior||Alert is Active (Making Noise)||Send AlertStarted||Send DeleteAlertSucceeded/DeleteAlertFailed||Send DeleteAlertsSucceeded/DeleteAlertsFailed|
|User says, "Stop Alert."||Send
|User stops an active alert locally with a physical button or GUI element.||None||Y||Y||N||N|
|User cancels an inactive alert with a speech request or through the Amazon Alexa app.||Send
|Alarm expired without playing. For example, the device wasn't powered on at the scheduled delivery time.||None||N||Y||N||N|
|An alert sounds, and the user says, "Alexa, snooze."||AVS sends a new
|An active alert is playing. The user says "Alexa, clear all alerts".||AVS sends a
Alerts interaction sequences
The following sections walk through common usage scenarios for users interacting with the AVS Alerts feature.
Set and stop a timer with a voice utterance
Consider a user who wants to set a 5-minute timer. When the user says, "Set a timer for five minutes," the device must capture the utterance and send a
Recognize event to AVS. AVS then responds with a series of directives telling the device what to do, and the device must act. Setting a timer or an alarm follows the standard interaction model between a device and AVS: ask a question or make a request, receive a response and act upon it, update AVS that something has occurred. If the device loses internet connectivity, it must send updates to AVS on the status of the alarm when internet connectivity is re-established.
The following sequence diagram illustrates the expected interaction between the device and AVS when a user sets a timer:
Setting a timer invokes the following message flow:
- When a user makes the request to set a timer, AVS sends a
Speakdirective that instructs the device to play the appropriate audio, such as "Five minutes, starting now." When the playback of Alexa speech begins, the device sends a
SpeechStartedevent to AVS.
- After completing playback of Alexa speech, the device sends a
SpeechFinishedevent to AVS, and AVS sends a
SetAlertdirective to the device on the downchannel stream.
- The device sets a timer for five minutes and send a
SetAlertSucceededevent to AVS.
- After five minutes elapse, the device notifies the user that the timer has expired and sends an
AlertStartedevent to AVS.
Stop a timer
Users should be able to stop a timer by using their voice or the Amazon Alexa app, and if applicable through a physical control, such as button on a device or the GUI of an app.
- When a user makes a stop request through a voice command or through the Amazon Alexa app, AVS sends a
DeleteAlertdirective to the device. When the device handles that directive, the device sends an
AlertStoppedevent and a
DeleteAlertSucceededevent to AVS.
- When a user stops a timer with a physical control, the device sends an
AlertStoppedevent to AVS.
Cancel an alarm with the Amazon Alexa app
Consider case where a user has set a 7:30 AM alarm on a device and wants to cancel that alarm.
- The user opens the Amazon Alexa app, where they have access to all active and inactive on-product alarms. The user navigates to alarms, and cancels the alarm set for 7:30 AM.
- AVS sends a
DeleteAlertdirective to the device on the downchannel stream.
- When the app receives the
DeleteAlertdirective, the device acts on the directive and cancels the alarm set for 7:30 AM, and then sends a
DeleteAlertSucceededevent to AVS.
The following sequence diagram illustrates the expected interaction between the device and AVS when a user cancels an alarm through the Amazon Alexa app.
Set a recurring alarm
The flow of directives and events for setting a recurring alarm are nearly identical (see Set a timer) to those for setting a timer. The main difference is that for a recurring alarm, AVS sends a new
SetAlert directive to your product each day unless a user cancels the recurring alarm.
The following sequence diagram illustrates the expected interaction between a device and AVS when a user sets a recurring alarm.
Snooze a playing alarm
Consider a scenario where a user set an alarm, the alarm begins to play, and a user utters a "snooze" command to stop the alarm temporarily and resume playing the alarm in nine minutes.
- When the user utters, "Alexa, snooze," the device streams the user speech to AVS, and AVS sends a new
SetAlertdirective with an updated
scheduledTimeto the device.
- The device checks if the
tokenfor the sounding alarm and the new
SetAlertdirective match. If the tokens match, the device cancels the sounding alarm, and set a new alarm for the
scheduledTimeincluded in the payload of the
The following sequence diagram illustrates the expected interaction between the device and AVS when a user snoozes an alarm:
For a complete list of directives and events necessary to support timers and alarms, see: