Enable Named Timers and Reminders

Named Timers and Reminders are part of the Alerts feature of the Alexa Voice Service (AVS). The Named Timers feature allows Alexa users to set and manage multiple timers at a time by giving an identifying name to each timer. Reminders are alerts that Alexa plays at a time specified by a user. To learn more about Alerts, see About Alexa Voice Service (AVS) Alerts.

The following utterances show how a user might 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."

Best practices for Named Timers and Reminders

Although enabling Named Timers or Reminders doesn't impact the AVS Interaction Model for a device, make sure that you understand how and when to deliver assets to the user.

  • The device should send all lifecycle events to AVS when appropriate, such as a SetAlertSucceeded event when a user sets a reminder locally, or an AlertStopped event when a user stops an actively playing reminder. For complete details, see the Alerts reference.
  • Have the device download and store any assets locally. The device is then able to play the locally downloaded asset at the scheduledTime.
  • If the Dialog channel is active, and you receive a SetAlert directive that includes the assets object, the device 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, the device must play the assets in the assetPlayOrder.

Implement support for named timers and reminders

The SetAlert directive supports the Alerts feature for Named Timers and Reminders, which allows AVS to send parameters to the device with instructions for sequenced playback of audio files and text-to-speech (TTS).

AVS delivers assets to a device in the payload of the directive as an unordered set. Each asset contains an assetId and url. The device should download and cache Alert assets for delivery to the user at the scheduledTime. The payload includes instructions for play order (assetPlayOrder), the number of times to play the sequence of assets (loopCount), and the duration between the start of each loop (loopPauseInMilliSeconds).

To implement support for named timers and reminders

  1. Update your code to support the following payload parameters:
    • assets
      • assetId
      • url
    • assetPlayOrder
    • backgroundAlertAsset
    • loopCount
    • loopPauseInMilliSeconds
  2. Update your code to support the REMINDER value for type.
  3. Make sure the device is able to download and cache the assets sent by AVS and deliver those assets to the user at the scheduledTime.
  4. Make sure that your implementation on the device follows the best practices outlined in Alerts Overview.

Enable Reminders

Before your device can receive Reminders, enable the Named Timers and Reminders capability in the AVS developer console.

To enable Named Timers and Reminders capability in the AVS developer console

  1. Log in to the AVS developer console with your Amazon developer credentials:

    AVS developer console.

  2. Navigate to Products, and create a new product or Edit an existing product, and follow the prompts to enter or update the appropriate information for your device.
  3. Under Product Details, in the Capabilities section, select Named Timers and Reminders to enable these features.

Example Reminder

The following example extends the SetAlert directive to support reminders:

View the example.+

SetAlert directive

The SetAlert directive instructs the device to set a timer, alarm, or reminder for a specific duration or time. A device might receive the SetAlert directive either when a user makes a speech request to set an alert, or when a user re-enables an already-set alert through 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 AVS sends an unrecognized value to the device, it should default to an ALARM.
Accepted values: TIMER, ALARM, REMINDER.
string
scheduledTime The scheduled time for an alert in ISO 8601 format. string
assets A list that contains audio assets to play 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 for the device to download and cache. The asset URL is valid for 60 minutes after the scheduledTime. As a best practice, Amazon recommends having the device download and store any assets locally. The device is then able to play the locally downloaded asset at the scheduledTime string
assetPlayOrder The sequence to play the audio assets. The list contains the assetIds.

Note: assetIds might appear multiple times in the list. When assetIds appear, play all assetIds. If your device fails to download and cache the assets, your device should use the audio files provided by Amazon.
list
backgroundAlertAsset Identifies the asset to play when the Alerts channel is in the background (see Interaction Model). The assets list provides the backgroundAlertAsset. If the payload doesn't include the backgroundAlertAsset, default to the Amazon provided sound asset. string
loopCount The number of times to play each sequence of assets. For example: If the value is 2, the device 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 user stops the alert.
long
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, the device 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 the channel is actively 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 isn't specified, is set to 0, or is shorter than the duration of the asset, there must not be any silence between asset loops.
long

Resources