Your Alexa Consoles
登录
登录
感谢您的访问。此页面目前仅提供英语版本。我们正在开发中文版本。谢谢您的理解。

Alerts Overview

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, SetAlert and DeleteAlert) and to send events that inform the Alexa Voice Service (AVS) an action was taken (for example, SetAlertSucceeded and DeleteAlertSucceeded).

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 AlertStopped event for each discarded alert.

To recap, your Alexa Built-in product must:

  1. Be able to act on previously set alerts if internet connectivity is lost.
  2. Use Network Time Protocol to manage a product's clock.
  3. 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 Speak directive 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 SpeechStarted event to AVS.
  • When playback of Alexa speech is complete, your product must send a SpeechFinished event to AVS.
  • AVS also sends a SetAlert directive to your product on the downchannel stream. An on-product timer must then be set for 5 minutes and a SetAlertSucceeded event 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 AlertStarted event 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 DeleteAlert directive to your product. When that directive is handled, your product must send an AlertStopped event and a DeleteAlertSucceeded event to AVS.
  • When the timer is stopped as the result of a button affordance your product must send an AlertStopped event 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.

Alerts Scenario 1

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.

  • A DeleteAlert directive is sent to your product on the downchannel stream. Up-to-this point, all user action has occurred in the Amazon Alexa app.

  • When the DeleteAlert directive 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.

Alerts Scenario 2

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.

Alerts Scenario 3

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 SetAlert directive.

This sequence diagram illustrates the expected interaction between your product and AVS when an alarm is snoozed.

Alerts Scenario 4

Lifecycle events

This table provides user actions and the lifecycle events your product must send to AVS.

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

Next Steps

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

Resources