Alerts Interface
The Alerts Interface exposes directives and events that are used to set, manage and cancel timers, alarms, and reminders. Your client must implement the logic necessary to manage timers, alarms, and reminders if internet connectivity is lost or if the on-product clock is out of sync with NTP. Please reference the Alerts Overview and the Interaction Model for additional implementation details.
Version Changes
- The Alerts interface has been enhanced to allow the deletion of multiple alerts via the
DeleteAlerts
directive,DeleteAlertsFailed
event, andDeleteAlertsSucceeded
event. SetVolume
andAdjustVolume
directives, and theVolumeChanged
event have been added to the Alerts interface. The addition of these directives and events enable the end user to control alert volume via the Amazon Alexa app.- Users can select custom alert tones within the Amazon Alexa app. See AVS UX Attention System for guidance on how to manage alerts, including custom alerts, for your product.
State Diagram
The following diagram illustrates state changes driven by the Alerts component. Boxes represent Alerts states and connectors indicate transitions.
Alerts supports the following states:
IDLE: Prior to a previously set alert going off, the Alerts component should be in the idle state. Alerts should also return to an idle state once an alert is stopped/finished. This can occur as the result of user speech, a physical button press, or GUI affordance.
FOREGROUND ALERT: Assuming an on-client alert has already been set, Alerts should transition from the idle state to the alert foreground state when an alert starts and the AlertStarted event is sent to the Alexa Voice Service.
This is only true if the Alerts channel is in the foreground, which implies the Dialog channel is inactive. For more information on channels and channel prioritization, please see Interaction Model.
When an alert is stopped via speech, button press, or GUI affordance, the Alerts component should transition from the alert foreground state to the idle state.
If the Dialog channel becomes active while an alert is going off, your Alerts component should transition from the foreground alert state to the background alert state as long as the Dialog channel is active. When the Dialog channel becomes inactive, it should return to the foreground alert state until it is stopped/finished.
BACKGROUND ALERT: The Alerts component should only transition to the background alert state when the Dialog channel is active. For more information on channels and channel prioritization see Interaction Model.

Capabilities API
To use version 1.3 of the Alerts interface, it must be declared in your call to the Capabilities API. For additional details, see Capabilities API.
Sample Object
{ "type": "AlexaInterface", "interface": "Alerts", "version": "1.3", "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
cannot 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
; if 8 alarms are set, you can only set 2 timers.Alerts 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 | Time the alert is scheduled in ISO 8601 format. | 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 | Time the alert is scheduled in ISO 8601 format. | string |
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.
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}} } } }
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 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. This asset may be downloaded and cached by your client. The URL provided is valid for 60 minutes after 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 | 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. |
long |
SetAlertSucceeded Event
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 Event
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 |
DeleteAlert Directive
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 |
DeleteAlertSucceeded Event
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 Event
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 |
DeleteAlerts Directive
This directive instructs your client to delete all existing alerts on a product. Each alert is identified by a unique token within the payload. Your client may receive the DeleteAlerts
directive as a result of a speech request to cancel/delete all alerts.
If one or more alerts fail to be deleted, the client must rollback and send a DeleteAlertsFailed
event to Alexa. Alexa will then retry until all alerts are deleted, at which point a DeleteAlertsSucceeded
event must be sent by your client.
DeleteAlerts
should be sent only if one or more existing alert tokens on the product fail to be deleted.Sample 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 |
DeleteAlertsSucceeded Event
The DeleteAlertsSucceeded
event must be sent to AVS after receiving a DeleteAlerts
directive, when the client successfully deletes or cancels all existing alerts within the tokens array.
DeleteAlertsSucceeded
event, please see Alerts Overview.Sample 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 product. | string |
DeleteAlertsFailed Event
The DeleteAlertsFailed
event must be sent to AVS after receiving a DeleteAlerts
directive, when the client fails to delete or cancel at least one of the existing alerts within the tokens array.
DeleteAlertsFailed
event, please see Alerts Overview.Sample 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 Event
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 Event
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 Event
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 Event
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 |
SetVolume Directive
This directive instructs a client to set the absolute volume level for an alert.
Sample 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 0 (min) to 100 (max). Accepted values: Any value between 0 and 100, inclusive. |
long |
AdjustVolume Directive
This directive instructs a client to adjust the relative volume level of an alert.
Sample 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 is used to increase or decrease volume in relation to the current volume setting. Accepted values: Any value between -100 and 100, inclusive. |
long |
VolumeChanged Event
This event must be sent to AVS after receiving either a SetVolume
or AdjustVolume
directive.
Sample 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 | This is the volume that is locally adjusted on your product. Accepted values: Volume must be a value between 0 (min) and 100 (max), inclusive. Important: If your product locally supports volume adjustment from 0 to 10, you must scale this to a range of 0 to 100. For example, when the user increases the volume to 8, AVS expects the volume value sent to be 80. |
long |
The Alerts Interface exposes directives and events that are used to set, manage and cancel timers, alarms, and reminders. Your client must implement the logic necessary to manage timers, alarms, and reminders if internet connectivity is lost or if the on-product clock is out of sync with NTP. Please reference the Alerts Overview and the Interaction Model for additional implementation details.
Version Changes
- The payload of the
SetAlert
directive has been updated to support named timers and reminders. This change is backward compatible.
State Diagram
The following diagram illustrates state changes driven by the Alerts component. Boxes represent Alerts states and connectors indicate transitions.
Alerts supports the following states:
IDLE: Prior to a previously set alert going off, the Alerts component should be in the idle state. Alerts should also return to an idle state once an alert is stopped/finished. This can occur as the result of user speech, a physical button press, or GUI affordance.
FOREGROUND ALERT: Assuming an on-client alert has already been set, Alerts should transition from the idle state to the alert foreground state when an alert starts and the AlertStarted event is sent to the Alexa Voice Service.
This is only true if the Alerts channel is in the foreground, which implies the Dialog channel is inactive. For more information on channels and channel prioritization, please see Interaction Model.
When an alert is stopped via speech, button press, or GUI affordance, the Alerts component should transition from the alert foreground state to the idle state.
If the Dialog channel becomes active while an alert is going off, your Alerts component should transition from the foreground alert state to the background alert state as long as the Dialog channel is active. When the Dialog channel becomes inactive, it should return to the foreground alert state until it is stopped/finished.
BACKGROUND ALERT: The Alerts component should only transition to the background alert state when the Dialog channel is active. For more information on channels and channel prioritization see Interaction Model.

Capabilities API
To use version 1.1 of the Alerts interface, it must be declared in your call to the Capabilities API. For additional details, see 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
cannot 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
; if 8 alarms are set, you can only set 2 timers.Alerts 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 | Time the alert is scheduled in ISO 8601 format. | 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 | Time the alert is scheduled in ISO 8601 format. | string |
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.
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}} } } }
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 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. This asset may be downloaded and cached by your client. The URL provided is valid for 60 minutes after 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 | 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. |
long |
SetAlertSucceeded Event
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 Event
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 |
DeleteAlert Directive
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 |
DeleteAlertSucceeded Event
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 Event
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 Event
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 Event
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 Event
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 Event
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 |
The Alerts Interface exposes directives and events that are used to set, manage and cancel timers, alarms. Your client must implement the logic necessary to manage timers, alarms if internet connectivity is lost or if the on-product clock is out of sync with NTP. Please reference the Alerts Overview and the Interaction Model for additional implementation details.
State Diagram
The following diagram illustrates state changes driven by the Alerts component. Boxes represent Alerts states and connectors indicate transitions.
Alerts supports the following states:
IDLE: Prior to a previously set alert going off, the Alerts component should be in the idle state. Alerts should also return to an idle state once an alert is stopped/finished. This can occur as the result of user speech, a physical button press, or GUI affordance.
FOREGROUND ALERT: Assuming an on-client alert has already been set, Alerts should transition from the idle state to the alert foreground state when an alert starts and the AlertStarted event is sent to the Alexa Voice Service.
This is only true if the Alerts channel is in the foreground, which implies the Dialog channel is inactive. For more information on channels and channel prioritization, please see Interaction Model.
When an alert is stopped via speech, button press, or GUI affordance, the Alerts component should transition from the alert foreground state to the idle state.
If the Dialog channel becomes active while an alert is going off, your Alerts component should transition from the foreground alert state to the background alert state as long as the Dialog channel is active. When the Dialog channel becomes inactive, it should return to the foreground alert state until it is stopped/finished.
BACKGROUND ALERT: The Alerts component should only transition to the background alert state when the Dialog channel is active. For more information on channels and channel prioritization see Interaction Model.

Capabilities API
To use version 1.0 of the Alerts interface, it must be declared in your call to the Capabilities API. For additional details, see Capabilities API.
Sample Object
{ "type": "AlexaInterface", "interface": "Alerts", "version": "1.0" }
Alerts 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 | Time the alert is scheduled in ISO 8601 format. | 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 | Time the alert is scheduled in ISO 8601 format. | string |
SetAlert Directive
This directive instructs your client to set a timer or alarm 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.
Sample Message
{ "directive": { "header": { "namespace": "Alerts", "name": "SetAlert", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "type": "{{STRING}}", "scheduledTime": "{{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 . |
string |
scheduledTime | The scheduled time for an alert in ISO 8601 format. | string |
SetAlertSucceeded Event
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 Event
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 |
DeleteAlert Directive
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 or alarm 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 |
DeleteAlertSucceeded Event
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 Event
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 Event
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 Event
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 Event
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 Event
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 |