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.

Alerts states

The following diagram illustrates state changes driven by the Alerts component. Boxes represent Alerts states and connectors represent transitions:

Alerts State Diagram
Click to enlarge

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 AlertStarted event 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 AlertStopped event 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.

Lifecycle events

The following table lists the user actions and the lifecycle events that the device sends to AVS.

User Action Server Behavior Alert is Active (Making Noise) Send AlertStarted Send DeleteAlertSucceeded/DeleteAlertFailed Send DeleteAlertsSucceeded/DeleteAlertsFailed
User says, "Stop Alert." Send DeleteAlert on the downchannel stream. Y Y Y N
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 DeleteAlert directive on the downchannel stream. N N Y N
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 SetAlert directive with the same token as the alert that the user snoozed. Y Y Y N
An active alert is playing. The user says "Alexa, clear all alerts". AVS sends a DeleteAlerts directive on the downchannel stream. Y Y N Y

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:

Alerts Scenario 1

Setting a timer invokes the following message flow:

  1. When a user makes the request to set a timer, AVS sends a Speak directive 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 SpeechStarted event to AVS.
  2. After completing playback of Alexa speech, the device sends a SpeechFinished event to AVS, and AVS sends a SetAlert directive to the device on the downchannel stream.
  3. The device sets a timer for five minutes and send a SetAlertSucceeded event to AVS.
  4. After five minutes elapse, the device notifies the user that the timer has expired and sends an AlertStarted event 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 DeleteAlert directive to the device. When the device handles that directive, the device sends an AlertStopped event and a DeleteAlertSucceeded event to AVS.
  • When a user stops a timer with a physical control, the device sends an AlertStopped event 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.

  1. 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.
  2. AVS sends a DeleteAlert directive to the device on the downchannel stream.
  3. When the app receives the DeleteAlert directive, the device acts on the directive and cancels the alarm set for 7:30 AM, and then sends a DeleteAlertSucceeded event 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.

Alerts Scenario 2

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.

Alerts Scenario 3

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.

  1. When the user utters, "Alexa, snooze," the device streams the user speech to AVS, and AVS sends a new SetAlert directive with an updated scheduledTime to the device.
  2. The device checks if the token for the sounding alarm and the new SetAlert directive match. If the tokens match, the device cancels the sounding alarm, and set a new alarm for the scheduledTime included in the payload of the SetAlert directive.

The following sequence diagram illustrates the expected interaction between the device and AVS when a user snoozes an alarm:

Alerts Scenario 4

Next steps

For a complete list of directives and events necessary to support timers and alarms, see:

Resources