Alerts 1.1
The Alerts Interface of the Alexa Voice Service (AVS) exposes directives and events that set, manage, and cancel timers, alarms, and reminders. For a user to set an alert, your client must have an active internet connection to receive directives that instruct your client to take action.
See the Alerts Overview and the Interaction Model for more implementation details.
Version changes
- The payload of the
SetAlert
directive now supports named timers and reminders. This change is backward compatible.
Capability assertion
Alerts 1.1 may be implemented by the device on its own behalf, but not on behalf of any connected endpoints.
New AVS integrations must assert support through Alexa.Discovery, but AVS continues support for legacy integrations through the Capabilities API.
Sample Object
{ "type": "AlexaInterface", "interface": "Alerts", "version": "1.1", "configurations": { "maximumAlerts": { "overall": {{INTEGER}}, "alarms": {{INTEGER}}, "timers": {{INTEGER}} } } }
Configuration Parameters
Parameter | Description | Type |
---|---|---|
maximumAlerts | An object that contains configuration information for your Alerts implementation. | object |
maximumAlerts.overall | The maximum number of combined alerts (timers and alarms) your product can store at a given time. | integer |
maximumAlerts.alarms | The maximum number of alarms your product can store at a given time. | integer |
maximumAlerts.timers | The maximum number of timers your product can store at a given time. | integer |
maximumAlerts.alarms
and maximumAlerts.timers
may exceed the value provided for maximumAlerts.overall
. For example, you can declare that maximumAlerts.overall
== 10
and that maximumAlerts.alarms
and maximumAlerts.timers
each == 8
; but if 7 alarms are set, you can only set 3 timers.Context
Alexa expects a client to report the status of all locally stored alerts with each event that requires context. Alerts are organized into two lists: allAlerts
and activeAlerts
. allAlerts
is a complete list of locally stored alerts. activeAlerts
is a list of alerts currently in focus or sounding for an end user.
To learn more about reporting Context, see Context Overview.
Sample Message
{ "header": { "namespace": "Alerts", "name": "AlertsState" }, "payload": { "allAlerts": [ { "token": "{{STRING}}", "type": "{{STRING}}", "scheduledTime": "{{STRING}}" } ], "activeAlerts": [ { "token": "{{STRING}}", "type": "{{STRING}}", "scheduledTime": "{{STRING}}" } ] } }
Payload Parameters
Parameter | Description | Type |
---|---|---|
allAlerts | Key/value pairs for allAlerts | object |
allAlerts.token | Alert token returned by Alexa when the alert was set. | string |
allAlerts.type | Identifies the alert type.
Accepted Values: TIMER, ALARM, REMINDER. |
string |
allAlerts.scheduledTime | Timestamp for when the alert is scheduled in YYYY-MM-DDThh:mm:ss±hhmm ISO 8601 format.
Example value: "2018-11-28T09:34:32+0000" |
string |
activeAlerts | Key/value pairs for activeAlerts | object |
activeAlerts.token | The token for the alert that is currently firing. | string |
activeAlerts.type | Identifies the alert type.
Accepted Values: TIMER or ALARM |
string |
activeAlerts.scheduledTime | Timestamp for when the alert is scheduled in YYYY-MM-DDThh:mm:ss±hhmm ISO 8601 format.
Example value: "2018-11-28T09:34:32+0000" |
string |
Directives
SetAlert
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.
If loopCount
is absent from the payload, the alert must sound for one hour or until it is stopped by the user (voice request or physical affordance).
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.
assets.url[i]
is unreachable, or if your client fails to download the associated files, it should play the audio files for the associated alert type provided by Amazon and adhere to the provided loopCount
and loopPauseInMilliSeconds
.Sample Message
{ "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": [ {{LIST}} ], "backgroundAlertAsset": "{{STRING}}", "loopCount": {{LONG}}, "loopPauseInMilliSeconds": {{LONG}}, "label": "{{STRING}}", "originalTime": "{{STRING}}" } } }
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 | Timestamp for when the alert is scheduled in YYYY-MM-DDThh:mm:ss±hhmm ISO 8601 format.
Example value: "2018-11-28T09:34:32+0000" |
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 for the client to download and cache. The URL expires in 24 hours, so have the device download the asset and store it locally before the asset expires. The device plays the locally downloaded asset at the scheduledTime . |
string |
assetPlayOrder | The sequence that audio assets must be played. The list is comprised of assetId s. Note: i) assetId s may appear multiple times in the list. When this occurs, all assetId s 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 | If present, the backgroundAlertAsset value will match an assetId in the assets list. If backgroundAlertAsset is not included in the payload, default to the Amazon provided sound in the Alexa sound library for AVS, which is available to download in the Alexa Voice Service > Resources section of the Developer Console. |
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 | 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. |
long |
label | A custom description label for the contents of the alert. For reminder alerts, this string represents a reminder's label. For timer alerts, this string represents a timer's name. This field isn't sent with all alerts, it's only sent if the label preexists. Examples: - Timer utterance: "Set a coffee timer for five minutes." The label is "coffee". - Reminder utterance: "Remind me to pick up kids from school at seven PM." The label is "pick up kids". |
string |
originalTime | The starting time that the alert is first set to, specified in the ISO 8601 extended format. Snoozing or deferring an alert doesn't modify this value. | string |
DeleteAlert
This directive is sent from AVS instructing your client to delete an existing alert. Your client may receive the DeleteAlert
directive as a result of a speech request to cancel/delete a timer, alarm, or reminder, or when a previously set alert is deleted using the Amazon Alexa app.
Sample Message
{ "directive": { "header": { "namespace": "Alerts", "name": "DeleteAlert", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" } } }
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 |
Events
SetAlertSucceeded
The SetAlertSucceeded
event must be sent to AVS after receiving a SetAlert
directive, when the client successfully sets the alert.
Sample Message
{ "event": { "header": { "namespace": "Alerts", "name": "SetAlertSucceeded", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
token | An opaque token provided by the SetAlert directive. |
string |
SetAlertFailed
The SetAlertFailed
event must be sent to AVS after receiving a SetAlert
directive, when the client fails to sets an alert.
Sample Message
{ "event": { "header": { "namespace": "Alerts", "name": "SetAlertFailed", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
token | An opaque token provided by the SetAlert directive. |
string |
DeleteAlertSucceeded
The DeleteAlertSucceeded
event must be sent to AVS after receiving a DeleteAlert
directive, when the client successfully deletes or cancels an existing alert.
DeleteAlertSucceeded
event, please see Alerts Overview.Sample Message
{ "event": { "header": { "namespace": "Alerts", "name": "DeleteAlertSucceeded", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
token | An opaque token provided by the DeleteAlert directive. |
string |
DeleteAlertFailed
The DeleteAlertFailed
event must be sent to AVS after receiving a DeleteAlert
directive, when the client fails to delete or cancel an existing alert.
DeleteAlertFailed
event, please see Alerts Overview.Sample Message
{ "event": { "header": { "namespace": "Alerts", "name": "DeleteAlertFailed", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
token | An opaque token provided by the DeleteAlert directive. |
string |
AlertStarted
The AlertStarted
event must be sent to AVS when an alert is triggered at its scheduled time.
AlertStarted
event, please see Alerts OverviewSample Message
{ "event": { "header": { "namespace": "Alerts", "name": "AlertStarted", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
token | An opaque token provided by the SetAlert directive. |
string |
AlertStopped
The AlertStopped
event must be sent to AVS when an active alert is stopped. An alert is stopped when:
- A
DeleteAlert
directive is received. After sending anAlertStopped
event, your client must inform AVS if the alert was successfully deleted with either aDeleteAlertSucceeded
event orDeleteAlertFailed
event. This interaction is illustrated in Alerts Overview. - A physical control (hardware button or GUI) is used to stop the alert.
- The
loopCount
is complete, or an alert without aloopCount
has played for an hour and is stopped locally.
StopAlert
event, please see Alerts Overview.Sample Message
{ "event": { "header": { "namespace": "Alerts", "name": "AlertStopped", "messageId": "{STRING}" }, "payload": { "token": "{{STRING}}" } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
token | An opaque token provided by the SetAlert directive. |
string |
AlertEnteredForeground
The AlertEnteredForeground
event must be sent from your client to AVS when an active alert enters the foreground (plays at full volume) or re-enters the foreground after a concurrent interaction on the Dialog channel finishes. For specific details on channel interaction, see Interaction Model.
Sample Message
{ "event": { "header": { "namespace": "Alerts", "name": "AlertEnteredForeground", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
token | An opaque token provided by the SetAlert directive. |
string |
AlertEnteredBackground
The AlertEnteredBackground
event must be sent from your client to AVS when an active alert exits the foreground (attenuates or pauses) while a concurrent interaction on the Dialog channel is occurring. For specific details on channel interaction, see Interaction Model.
Sample Message
{ "event": { "header": { "namespace": "Alerts", "name": "AlertEnteredBackground", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
token | An opaque token provided in the SetAlert directive. |
string |
Last updated: Aug 11, 2021