Alerts 1.4
The Alerts Interface exposes directives and events to manage timers, alarms, and reminders for the Alexa Voice Service (AVS). Your client must have an active internet connection to support the on-going lifecycle of these directives and events. This is important because a user might update a setting while the device is offline and they expect it to work without any other interactions – for example, setting an alarm for later that day.
See the Alerts Overview and the Interaction Model for more implementation details and conceptual information.
Version changes
- Support for device-reported control over alarm volume, enabling ascending alarms.
- ADDED
SetAlarmVolumeRamp
directive - ADDED
AlarmVolumeRampReport
event - ADDED
AlarmVolumeRampChanged
event
- ADDED
Capability assertion
A device can implement Alerts 1.4 on its own behalf, but not on behalf of any connected endpoints.
New AVS integrations must assert support through Alexa.Discovery. However, Alexa continues to support existing integrations using the Capabilities API.
Sample Object
{ "type": "AlexaInterface", "interface": "Alerts", "version": "1.4", "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 | Maximum total number of timers plus alarms stored on a device at a given time. | integer |
maximumAlerts.alarms | Maximum number of alarms stored on a device at a given time. | integer |
maximumAlerts.timers | Maximum number of timers stored on a device at a given time. | integer |
maximumAlerts.alarms
and maximumAlerts.timers
might exceed the value provided for maximumAlerts.overall
. For example, if you declare that maximumAlerts.overall
== 10
and that maximumAlerts.alarms
and maximumAlerts.timers
each == 8
; but a user sets seven alarms, the user is then limited to setting three timers.Context
Alexa expects a client to report the status of all locally stored alerts with each event that requires context. Individual alerts belong to one of two categories: allAlerts
and activeAlerts
. allAlerts
is a complete list of locally stored alerts. activeAlerts
is a list of alerts in focus or sounding for a user.
To learn more about reporting Context, see Context Overview.
Example 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 user sets the alert. | 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 current active alert. | 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
The SetAlert
directive instructs your client to set a timer, alarm, or reminder for a specific duration or time. Clients receive the SetAlert
directive when a user makes a speech request to set or re-enable an alert through the Amazon Alexa app.
If loopCount
is absent from the payload, the alert must sound for one hour or until stops the alert with a voice request or physically interacting with the client.
AVS-provided assets
take precedence over locally stored audio files. If AVS provides assets
, the client must play them 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
.Example 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 |
string |
scheduledTime |
Timestamp for when the alert is scheduled, in YYYY-MM-DDThh:mm:ss±hhmm ISO 8601 format. |
string |
assets |
List containing audio assets to play for 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 |
string |
assetPlayOrder |
The sequence that audio assets must be played. The list contains |
list |
backgroundAlertAsset |
If present, the |
string |
loopCount |
The number of times each sequence of assets must be played. For example: If the value is |
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 |
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.
|
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
AVS sends a DeleteAlert
directive to the client to delete an existing alert. The client receives the DeleteAlert
directive when a user makes a speech request to cancel or delete a timer, alarm, or reminder, or deletes an existing set alert using the Amazon Alexa app.
Example 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 |
DeleteAlerts
The DeleteAlerts
directive instructs a client to delete all its existing alerts. A client receives the DeleteAlerts
directive when a user makes a speech request to cancel/delete all alerts. Use the tokens
array to group the identifiers for individual alerts.
- After deleting all alerts found in the
tokens
array on the client, send aDeleteAlertsSucceeded
event to AVS. - If the client is unable to actually delete any alerts found on the client that are present in the
tokens
array, send aDeleteAlertsFailed
event to AVS.
Example message
{ "directive": { "header": { "namespace": "Alerts", "name": "DeleteAlerts", "messageId": "{{STRING}}" }, "payload": { "tokens": ["{{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 |
---|---|---|
tokens | An array of tokens. Each token is a string that uniquely represents an alert on the product. | string |
SetVolume
The SetVolume
directive instructs a client to set the absolute volume level for an alert.
Example message
{ "directive": { "header": { "namespace": "Alerts", "name": "SetVolume", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "volume": {{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 |
---|---|---|
volume | The absolute volume level scaled from a minimum of 0 min to a maximum of 100. Accepted values: Any value between 0 and 100, inclusive. |
long |
AdjustVolume
The AdjustVolume
directive instructs a client to adjust the relative volume level of an alert.
Example message
{ "directive": { "header": { "namespace": "Alerts", "name": "AdjustVolume", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "volume": {{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 |
---|---|---|
volume | The relative volume adjustment. A positive or negative long value that increases or decreases volume in relation to the current volume setting. Accepted values: Any value between -100 and 100, inclusive. |
long |
SetAlarmVolumeRamp
The SetAlarmVolumeRamp
directive instructs a client to enable or disable an ascending alarm for an alert.
After receiving the directive, update the ascending alarm setting on the device and send an AlarmVolumeRampReport
event.
{
"directive": {
"header": {
"namespace": "Alerts",
"name": "SetAlarmVolumeRamp",
"messageId": "{{STRING}}"
},
"payload": {
"alarmVolumeRamp": "{{STRING}}"
}
}
}
Header parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
alarmVolumeRamp | Behavior of the alarm volume. Possible values: • ASCENDING : an alarm tone starts at a lower volume and ascends over time to the maximum level set by the user.• NONE : Alarm volume rings without a volume change. |
string |
Events
SetAlertSucceeded
Send the SetAlertSucceeded
event to AVS after receiving a SetAlert
directive and setting the alert on the client.
{ "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
Send the SetAlertFailed
event to AVS after receiving a SetAlert
directive and failing to set the alert on the client.
Example 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
Send the DeleteAlertSucceeded
event to AVS after receiving a DeleteAlert
directive, and the client deletes or cancels the specified alert.
DeleteAlertSucceeded
event, please see Alerts Overview.Example 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
Send the DeleteAlertFailed
event to AVS after the client receives a DeleteAlert
directive, but fails to delete or cancel the specified alert.
DeleteAlertFailed
event, please see Alerts Overview.Example 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 |
DeleteAlertsSucceeded
Send the DeleteAlertsSucceeded
event to AVS after receiving a DeleteAlerts
directive, after the client deletes or cancels all existing alerts within the tokens array.
For more information about when to send the DeleteAlertsSucceeded
event, see Alerts Overview.
Example message
{ "event": { "header": { "namespace": "Alerts", "name": "DeleteAlertsSucceeded", "messageId": "{{STRING}}" }, "payload": { "tokens": ["{{STRING}}",...] } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
tokens | An array of tokens. Each token is a string that uniquely represents an alert on the client. | string |
DeleteAlertsFailed
Send a DeleteAlertsFailed
event to AVS after receiving a DeleteAlerts
directive, if the client is able to find but fails to delete or cancel at least one of the existing alerts within the tokens array.
If the client fails to delete one or more alerts, the client must rollback and send a DeleteAlertsFailed
event to Alexa. Alexa then retries the request until the client is able to delete all alerts and then sends a DeleteAlertsSucceeded
event to AVS.
DeleteAlertsFailed
event if the client is able to find one or more identifiers but is unable to actually delete them.For more information about when to send the DeleteAlertsFailed
event, see Alerts Overview.
Example message
{ "event": { "header": { "namespace": "Alerts", "name": "DeleteAlertsFailed", "messageId": "{{STRING}}" }, "payload": { "tokens": ["{{STRING}}",...] } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
tokens | An array of tokens. Each token is a string that uniquely represents an alert on the product. | string |
AlertStarted
Send the AlertStarted
event to AVS when an alert starts at its scheduled time.
For more details about when to send the AlertStarted
event, see Alerts Overview.
Example 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
Send the AlertStopped
event to AVS when an active alert ends for any of the following reasons:
- The client receives a
DeleteAlert
directive. After sending anAlertStopped
event, your client must inform AVS if it could delete the alert with either aDeleteAlertSucceeded
event orDeleteAlertFailed
event. - A user uses a physical control (hardware button or GUI) to stop the alert.
- The
loopCount
is complete, or an alert without aloopCount
has played for one hour on the client.
See Alerts Overview for more information about sending AlertStopped
.
Example 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
A client sends the AlertEnteredForeground
event to AVS when an active alert enters the foreground by playing at full volume or re-enters the foreground after a concurrent interaction on the Dialog channel completes. For specific details on channel interaction, see Interaction Model.
Example 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 client sends the AlertEnteredBackground
event to AVS when an active alert exits the foreground by attenuating or pausing, while a concurrent interaction on the Dialog channel is occurring. For specific details on channel interaction, see Interaction Model.
Example 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 |
VolumeChanged
The client sends a VolumeChanged
event to AVS after receiving either a SetVolume
or AdjustVolume
directive.
Example message
{ "event": { "header": { "namespace": "Alerts", "name": "VolumeChanged", "messageId": "{{STRING}}" }, "payload": { "volume": {{LONG}} } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
volume | The locally adjusted the volume on the client. Accepted values: Volume must be a value between 0 and 100, inclusive. Important: If the client supports a volume range from 0 to 10, map the local range to a range of 0 to 100. For example, when the user locally increases the volume to 8, AVS expects the volume value sent to be 80. |
long |
AlarmVolumeRampReport
The AlarmVolumeRampReport
event informs AVS of the current ascending alarm value on the device. The device sends this event in response to a SetAlarmVolumeRamp
directive sent by Alexa.
Send AlarmVolumeRampReport
under the following conditions:
- The device updates the ascending alarm value in response to receiving a
SetAlarmVolumeRamp
directive. - The device fails to update the ascending alarm value in response to a
SetAlarmVolumeRamp
directive.
{
"event": {
"header": {
"namespace": "Alerts",
"name": "AlarmVolumeRampReport",
"messageId": "{{STRING}}"
},
"payload": {
"alarmVolumeRamp" : "{{STRING}}"
}
}
}
Header parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
alarmVolumeRamp | Behavior of the alarm volume. Possible values: • ASCENDING : an alarm tone starts at a lower volume and ascends over time to maximum level set by the user. • NONE : Alarm volume rings without a volume change. |
string |
AlarmVolumeRampChanged
Send the AlarmVolumeRampChanged
event when the ascending alarm value changes locally on the device. This can occur if a device is offline and a user updates the settings. In this case, you would send an AlarmVolumeRampChanged
when the device comes back online. This sends the current ascending alarm value to AVS.
{
"event": {
"header": {
"namespace": "Alerts",
"name": "AlarmVolumeRampChanged",
"messageId": "{{STRING}}"
},
"payload": {
"alarmVolumeRamp": "{{STRING}}"
}
}
}
Header parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
alarmVolumeRamp | Behavior of the alarm volume. Possible values: • ASCENDING : an alarm tone starts at a lower volume and ascends over time to maximum level set by the user.• NONE : Alarm volume rings without a volume change. |
string |
Last updated: Jul 15, 2021