Alerts Overview

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

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

Lifecycle events

The following table lists the user actions and the lifecycle events client 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 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 DeleteAlert directive on the downchannel stream N N Y N
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 SetAlert directive is sent with the same token as the alert that was snoozed. Y Y Y N
An alert is currently playing. The user says "Alexa, clear all alerts". DeleteAlerts is sent 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 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:

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 client to play the appropriate audio, such as "Five minutes, starting now." When the playback of Alexa speech begins, the client sends a SpeechStarted event to AVS.
  2. After completing playback of Alexa speech, the client sends a SpeechFinished event to AVS, and AVS sends a SetAlert directive to the client on the downchannel stream.
  3. The client sets a timer for five minutes and send a SetAlertSucceeded event to AVS.
  4. After five minutes elapse, the client 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 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 DeleteAlert directive to the client. When the client handles that directive, the client sends an AlertStopped event and a DeleteAlertSucceeded event to AVS.
  • When a user stops a timer with a physical control, the client sends an AlertStopped event 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.

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

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 client 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 client streams the user speech to AVS, and AVS sends a new SetAlert directive with an updated scheduledTime to the client.
  2. The client checks if the token for the sounding alarm and the new SetAlert directive match. If the tokens match, the client 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 client 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