Alerts 1.0

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.

Capability assertion

Alerts 1.0 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.0"
}

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 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}}",
            "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.		 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
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 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

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.

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.

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.

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

The AlertStopped event must be sent to AVS when an active alert is stopped. An alert is stopped when:

  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) is used to stop the alert.
  3. The loopCount is complete, or an alert without a loopCount has played for an hour and is stopped locally.

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