Enable Named Timers and Reminders

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

AVS delivers assets to a client in the payload of the directive as an unordered set (assets). Each asset contains an assetId and url. Your client 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).

Example utterances

After you've updated your client code, the following example 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."

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 is able to 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, enable the device capability in the AVS developer console:

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

    AVS console login page.

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

Best practices

Implementing Named Timers or Reminders doesn't impact the AVS Interaction Model for a client; however, it's important to understand how and when to deliver assets to the user.

  • The client should send all lifecycle events to AVS when appropriate, such as SetAlertSucceeded when a user sets a reminder locally, or AlertStopped when a user stops a sounding reminder. For complete details, see the Alerts interface.
  • Have your client download and store any assets locally. The client 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, 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 extending the SetAlert directive to support reminders.

Click here to expand +

SetAlert Directive

The SetAlert directive instructs your client to set a timer, alarm, or reminder for a specific duration or time. Your client could receive the SetAlert directive as a result of a speech request to set an alert, or when an already-set alert is re-enabled 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 an unrecognized value is sent to your client, 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 client to download and cache. The asset URL is valid for 60 minutes after the scheduledTime. As a best practice, Amazon recommends having the client download and store any assets locally. The client is then able to play the locally downloaded asset at the scheduledTime string
assetPlayOrder The sequence that audio assets must be played. The list contains the assetIds.

Note: assetIds might appear multiple times in the list. When assetIds appear, play all assetIds. If your client 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 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 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, 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 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