Your Alexa Dashboards Settings

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.

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.

Alerts State Diagram
Click to enlarge

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.

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

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.

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.

Sample 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 can be stopped in one of two ways:

  1. A DeleteAlert directive is received. After sending an AlertStopped event, your client must inform AVS if the alert was successfully deleted with either a DeleteAlertSucceeded event or DeleteAlertFailed event. This interaction is illustrated in Alerts Overview.
  2. A physical control (hardware button or GUI).

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

Additional Interfaces

Jump to the top of this document. Use the sidebar to navigate to additional interfaces.

Resources