Enable Named Timers and Reminders

The SetAlert directive has been extended to support named timers and reminders. This change allows Alexa to send parameters to your client with instructions for sequenced playback of audio files and text-to-speech (TTS).

Assets are delivered to your client in the directive's payload as an unordered set (assets). Each asset contains an assetId and url. These assets must be downloaded and cached for delivery to the user at the scheduledTime. The payload includes instructions for play order (assetPlayOrder), the number of times a sequence of assets should be played (loopCount), and the duration between the start of each loop (loopPauseInMilliSeconds).

Your client is expected to send all lifecycle events when applicable, such as SetAlertSucceeded when the reminder is set locally, or AlertStopped when a user stops a sounding reminder. For complete details, see the Alerts interface.

Sample Utterances

After you've updated your client code, here are some examples for how a user may set a named timer or a reminder:

  • "Alexa, set a cooking timer for 10 minutes."
  • "Alexa, set a reminder to call mom at 2 P.M. on Saturday."
  • "Alexa, remind me to take out the trash on Tuesday at 8 A.M."

How To Prepare for Named Timers and Reminders

  1. Update your client code to support new payload parameters:
    • assets
      • assetId
      • url
    • assetPlayOrder
    • backgroundAlertAsset
    • loopCount
    • loopPauseInMilliSeconds
  2. Update your client code to support the REMINDER value for type.
  3. Make sure your client can download and cache assets sent by AVS and deliver them to the user at the scheduledTime.
  4. Make sure that your product adheres to the best practices outlined in Alerts Overview.

How to Enable Reminders

To start receiving Reminders, you'll need to enable the device capability in the AVS developer console.

  1. Click here to login.
  2. Create a new product or Edit an existing product.
  3. Click Device Capabilities, and select Named Timers and Reminders.

Interaction Model

This update does not impact the AVS Interaction Model, however, it's important to understand how and when assets should be delivered to the user.

  • If the Dialog channel is active, and you receive a SetAlert directive that includes the assets object, your client must play the locally stored audio file in short alert mode as long as the Dialog channel remains active.

  • If the Dialog channel is inactive, and you receive a SetAlert directive that includes the assets object, your client must play the assets in the assetPlayOrder.

Example Reminder

This example illustrates how the SetAlert directive has been extended to support reminders.

Click here to expand +

SetAlert Directive

This directive instructs your client to set a timer, alarm, or reminder for a specific duration or time. Your client may receive the SetAlert directive as a result of a speech request to set an alert, or when a previously set alert is re-enabled using the Amazon Alexa app.

    "directive": {
        "header": {
            "namespace": "Alerts",
            "name": "SetAlert",
            "messageId": "{{STRING}}",
            "dialogRequestId": "{{STRING}}"
        "payload": {
            "token": "{{STRING}}",
            "type": "{{STRING}}",
            "scheduledTime": "{{STRING}}",
            "assets": [
                    "assetId": "{{STRING}}",
                    "url": "{{STRING}}"
                    "assetId": "{{STRING}}",
                    "url": "{{STRING}}"
            "assetPlayOrder": ["{{STRING}}", "{{STRING}}", ... ],
            "backgroundAlertAsset": "{{STRING}}",
            "loopCount": {{LONG}},
            "loopPauseInMilliSeconds": {{LONG}}

Header Parameters

Parameter Description Type
messageId A unique ID used to represent a specific message. string
dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

Payload Parameters

Parameter Description Type
token An opaque token that uniquely identifies the alert. string
type Identifies the alert type. If an unrecognized value is sent to your client, it should default to an ALARM.
Accepted values: TIMER, ALARM, REMINDER.
scheduledTime The scheduled time for an alert in ISO 8601 format. string
assets A list that contains audio assets to be played to the user. list
assets[i].assetId A unique identifier for the audio asset. string
assets[i].url Identifies the location of the asset in the cloud. The asset must be downloaded and cached by your client. The URL provided is valid until the scheduledTime. string
assetPlayOrder The sequence that audio assets must be played. The list is comprised of assetIds.

Note: i) assetIds may appear multiple times in the list. When this occurs, all assetIds must be played. ii) If your client fails to download and cache the assets, your device should use the audio files provided by Amazon.
backgroundAlertAsset Identifies the asset that must be played when the Alerts channel is in the background (see Interaction Model). The backgroundAlertAsset is provided provided in the assets list. If backgroundAlertAsset is not included in the payload, default to the Amazon provided sound asset. string
loopCount The number of times each sequence of assets must be played. For example: If the value is 2, your client must loop through assetPlayOrder two times.

Note: If loopCount is absent from the payload, you must loop the assets for one hour, or until the alert is stopped by the user.
loopPauseInMilliseconds Duration between the beginnings of each asset loop, which includes the asset rendering time. For example: If a single alarm sound has a 200-millisecond duration and loopPauseInMilliSeconds is 700, assuming loopCount is greater than 1, your client must render 500 milliseconds of silence between the end of one instance of the alarm sound and the beginning of the next.

If the Alerts channel is sent to the background (regardless of whether it is currently rendering the asset or silent between loops), wait the full duration of loopPauseInMilliSeconds before rendering the background asset. If it regains foreground focus, begin rendering the foreground asset immediately.

Note: If this value is not specified, is set to 0, or is shorter than the duration of the asset, there must not be any silence between asset loops.