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 anAlertStopped
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 theassets
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 theassets
object, the device must play theassets
in theassetPlayOrder
.
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
- Update your code to support the following payload parameters:
assets
assetId
url
assetPlayOrder
backgroundAlertAsset
loopCount
loopPauseInMilliSeconds
- Update your code to support the
REMINDER
value fortype
. - 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
. - 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
-
Log in to the AVS developer console with your Amazon developer credentials:
- 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.
- 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.
assets
take precedence over locally stored audio files. Play provided assets
for the user in the order provided in the assetPlayOrder
list. Otherwise, use the audio files for alerts provided by Amazon.{ "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 assetId s. Note: assetId s might appear multiple times in the list. When assetId s appear, play all assetId s. 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
Last updated: Dec 15, 2020