Enable Named Timers and Reminders

Important: This change is backwards compatible.

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 pause duration between loops (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.

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.

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.

Important: Cloud provided assets take precedence over locally stored audio files. If assets are provided they must be played for the user in the order provided in the assetPlayOrder list. Otherwise, use the audio files for alerts provided by Amazon.

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

list

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.

long

loopPauseInMilliseconds

Pause duration between each asset loop. For example: If the loopPauseInMilliseconds is 300 and the loopCount is 3, your client must pause for 300 millisecond between each asset loop.

Note: If this value is not specified or is set to 0, there must not be any pause between asset loops.