The Alexa Voice Service (AVS) includes an Alerts feature that enables users to set, manage, and cancel timers, alarms, and reminders. This page discusses 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.
- Alerts states
- Locally managing alerts
- Amazon Alexa app support
- Lifecycle events
- Alerts interaction sequences
- Next steps
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 also return to an idle state after an alert ends. An alert ends as the result of user speech, a physical button press, or GUI affordance.
- FOREGROUND ALERT: When a user sets an on-client alert, Alerts should transition from the idle state to the alert foreground state when an alert starts, and the client sends the
AlertStartedevent to AVS.
- When the Alerts channel is in the foreground, the Dialog channel should be inactive. For more information on channels and channel prioritization, see Interaction Model.
- When a user stops an alert via speech, button press, or GUI affordance, the Alerts component should transition from the alert foreground state to the idle state.
- If the Dialog channel becomes active while 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 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 information on channels and channel prioritization see Interaction Model.
Locally managing alerts
Use the following requirements to locally manage clock and alert behavior on the client:
- Local clock management: Managing a client's clock is key to ensuring that alerts work as designed. AVS sends all directives in UTC time. When a user tells your product to "Set a timer for three minutes," AVS takes into account that user's time zone and determines the correct UTC time that corresponds to the request. If a user adjusted the client's locally, alerts might not function properly. To prevent synching issues, the Network Time Protocol (NTP) for clock synchronization.
- Loss of internet connectivity: Your client must have the ability to act on existing set alerts if the client loses internet connectivity. For example, if a user sets an alarm for 7:30am before going to sleep, and the client loses internet connectivity during the night, the client must have the ability to still play the alert at 7:30am.
Power outages or client reboots: In the event of a power outage or reboot, the client must have the ability to persist and restore existing alerts from local storage. The client isn't required to send any events notifying Alexa that the alerts were re-set.
If a user interrupts a scheduled alert by powering off or rebooting a client, adhere to the following rules:
- If the alerts were scheduled to go off in the last 30 minutes, the client must trigger the alerts and send all corresponding events.
- If more than 30 minutes have elapsed from an alert's scheduled delivery, discard the alerts and your client must send AVS an
AlertStoppedevent for each discarded alert.
Amazon Alexa app support
The Alerts interface v1.3 or later supports the ability of users to adjust alarm and timer settings via the Amazon Alexa app.
The following table lists the user actions and the lifecycle events client 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 control (button or GUI)||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 was not powered on at time of scheduled delivery.||None||N||Y||N||N|
|An alert sounds, and the user says, "Alexa, snooze."||A new
|An alert is currently playing. The user says "Alexa, clear all alerts".||
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 voice
Consider a user who wants to set a 5-minute timer. When the user says, "Set a timer for five minutes," the client must capture the user's speech and send a
Recognize event to AVS. AVS then responds with a series of directives telling the client what to do, and the client must take action. Setting a timer or an alarm follows the standard interaction model between a client and AVS: ask a question or make a request, receive a response and act upon it, update AVS that something has occurred. If the client 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 client 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 client to play the appropriate audio, such as "Five minutes, starting now." When the playback of Alexa speech begins, the client sends a
SpeechStartedevent to AVS.
- After completing playback of Alexa speech, the client sends a
SpeechFinishedevent to AVS, and AVS sends a
SetAlertdirective to the client on the downchannel stream.
- The client sets a timer for five minutes and send a
SetAlertSucceededevent to AVS.
- After five minutes elapse, the client 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 using 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 via voice or through the Amazon Alexa app, AVS sends a
DeleteAlertdirective to the client. When the client handles that directive, the client sends an
AlertStoppedevent and a
DeleteAlertSucceededevent to AVS.
- When a user stops a timer with a physical control, the client sends an
AlertStoppedevent to AVS.
Cancel an alarm using the Amazon Alexa app
Consider case where a user has set a 7:30am alarm on a client 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:30am.
- AVS sends a
DeleteAlertdirective to the client on the downchannel stream.
- When the app receives the
DeleteAlertdirective, the client acts on the directive and cancels the alarm set for 7:30am, and then sends a
DeleteAlertSucceededevent to AVS.
The following sequence diagram illustrates the expected interaction between the client and AVS when a user cancels an alarm using 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 client 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 client streams the user speech to AVS, and AVS sends a new
SetAlertdirective with an updated
scheduledTimeto the client.
- The client checks if the
tokenfor the sounding alarm and the new
SetAlertdirective match. If the tokens match, the client 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 client and AVS when a user snoozes an alarm:
For a complete list of directives and events necessary to support timers and alarms, see: