- Integration with Amazon Alexa app
- Scenario 1: Set a timer with voice
- Scenario 2: Cancel an alarm using the Amazon Alexa App
- Scenario 3: Set a recurring alarm
- Scenario 4: Snooze a sounding alarm
- Lifecycle events
- Next Steps
When it comes to Alerts, users will typically interact with your Alexa Built-in product in the following ways: setting a timer, setting an alarm, setting a reminder or canceling a timer, alarm or reminder. For a user to set an alert, your product must have an active internet connection. This is required to receive directives that instruct your product to take action (for example,
DeleteAlert) and to send events that inform the Alexa Voice Service (AVS) an action was taken (for example,
Your product must have the ability to act on previously set alerts if internet connectivity is lost. For example, if a user sets an alarm for 7:30 A.M. before going to sleep, and your product loses internet connectivity during the night, your product must have the ability to play the alert at 7:30 A.M. Executing alerts following the loss of internet connectivity ensures a positive user experience.
Managing your product's clock is key to ensuring that alerts work as designed. All directives sent from AVS are returned in UTC time. When a user tells your product to "Set a timer for 3 minutes," AVS takes into account that user's time zone and determines the correct UTC time that corresponds to the request. If the product's time has been adjusted locally, it is possible that alerts will not function properly. For this reason, Amazon suggests using the Network Time Protocol (NTP) for clock synchronization.
In the event of a power outage or when a reboot is required, your product must have the ability to persist and restore alerts. If the alerts are scheduled to go off in the future, your product must set the alerts locally. Your product does not need to send any events notifying Alexa that the alerts have been set again. In the case that your product is powered off or rebooting when an alert is scheduled to go off, it must adhere to the following rules:
- If the alerts were scheduled to go off in the last 30 minutes, your product must trigger the alerts and send all corresponding events.
- If more than 30 minutes have elapsed from an alert's scheduled delivery, it must be discarded and your product must send AVS an
AlertStoppedevent for each discarded alert.
To recap, your Alexa Built-in product must:
- Be able to act on previously set alerts if internet connectivity is lost.
- Use Network Time Protocol to manage a product's clock.
- Be able to act on previously set alerts if a product loses power or reboots.
The following examples should be used to further your understanding of how alerts work with AVS. These scenarios assume:
- Your product has been designed to handle user speech and act upon the directives it receives from AVS.
- Your product has established the downchannel to receive cloud-initiated directives. For more information, see Managing an HTTP/2 Connection with AVS.
- Your product will update AVS when events occur.
- All events are sent in individual event streams.
Integration with Amazon Alexa app
If you've implemented the Alerts interface v1.3 or later with the Capabilities API users can adjust alarm volumes and select custom alert tones via the Amazon Alexa app. Note: This applies to alarms, timers, and notifications, but not reminders.
Scenario 1: Set a timer with voice
A user wants to set a timer for 5 minutes. When the user says, "Set a timer for 5 minutes," your product must capture the user's speech and send a
Recognize event to AVS. AVS will then respond with a series of directives telling your product what to do, and your product must take action. This should sound familiar. That's because setting a timer or an alarm follows the standard interaction model between your product and AVS: ask a question or make a request, receive a response and act upon it, update AVS that something has occurred.
This is the message flow when setting a timer:
- When a user makes the request to set a timer, AVS sends a
Speakdirective that instructs your product to playback attached audio. In this scenario, "5 minutes, starting now." When the playback of Alexa speech begins, your product must send a
SpeechStartedevent to AVS.
- When playback of Alexa speech is complete, your product must send a
SpeechFinishedevent to AVS.
- AVS also sends a
SetAlertdirective to your product on the downchannel stream. An on-product timer must then be set for 5 minutes and a
SetAlertSucceededevent must be sent to AVS. Your product must have the logic necessary to set the timer as well as act upon the timer's expiration.
- After 5 minutes have elapsed, your product must notify the user that the timer has expired and send an
AlertStartedevent to AVS.
Your user should be able to stop the timer using voice or the Amazon Alexa app, and if applicable through a physical control (button or GUI).
- When the stop request is made via voice or through the Amazon Alexa app, AVS will send a
DeleteAlertdirective to your product. When that directive is handled, your product must send an
AlertStoppedevent and a
DeleteAlertSucceededevent to AVS.
- When the timer is stopped as the result of a button affordance your product must send an
AlertStoppedevent to AVS.
If implemented correctly, after the timer is set on your product, it must function without internet connectivity. However, a connection is required to notify AVS that events have occurred. As such, your product must have the logic necessary to update AVS on the status of the timer when internet connectivity is re-established.
The sequence diagram below illustrates the expected interaction between your product and AVS when a timer is set.
Scenario 2: Cancel an alarm using the Amazon Alexa App
For the purposes of this scenario, it should be assumed that an alarm was successfully set and the user wants to cancel that alarm.
The user opens the Amazon Alexa app, where they have access to all on-product alarms (active and inactive). The user navigates to alarms, and cancels the alarm set for 7:30 A.M.
DeleteAlertdirective is sent to your product on the downchannel stream. Up-to-this point, all user action has occurred in the Amazon Alexa app.
DeleteAlertdirective is received, your product must be capable of acting on the directive and canceling the alarm set for 7:30 A.M. This includes sending a DeleteAlertSucceeded event to AVS after the alarm has been deleted.
This sequence diagram illustrates the expected interaction between your product and AVS when an alarm is cancelled using the Amazon Alexa app.
Scenario 3: Set a recurring alarm
The process for setting a recurring alarm on your product is similar to setting a timer. The flow of directives and events are nearly identical (see Scenario 1), the only difference is AVS will send a new
SetAlert directive to your product each day until the recurring alarm is cancelled.
This sequence diagram illustrates the expected interaction between your product and AVS when a recurring alarm is set.
Scenario 4: Snooze a sounding alarm
For the purposes of this scenario, it should be assumed that an alarm was successfully set and is currently sounding.
When an alarm is sounding and a user says, "Alexa, snooze", a few things happen. User speech is streamed to AVS, and a new
SetAlert directive with an updated
scheduledTime is sent to your product. Your product must check if the
token for the sounding alarm and the new
SetAlert directive match. If the tokens match, your product must cancel the sounding alarm, and set a new alarm for the
scheduledTime included in the payload of the
This sequence diagram illustrates the expected interaction between your product and AVS when an alarm is snoozed.
This table provides user actions and the lifecycle events your product must send to AVS.
DeleteAlertFailedare only sent in response to a
DeleteAlertdirective. Do not 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."||
|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||
|Alarm expired without playing (for example, 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
|There is an alert currently playing. The user says "Alexa, clear all alerts".||
For a complete list of directives and events necessary to implement timers and alarms, see: