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

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

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.

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

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 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 scheduledTime. As a best practice, Amazon recommends having the client download and store any assets locally. The client is then able to play the locally downloaded asset at the scheduledTime. string
assetPlayOrder The sequence that audio assets must be played. The list contains assetIds.

Note: assetIds might appear more than one time in the list, which must all be played. 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 matches an assetId in the assets list. If backgroundAlertAsset isn't 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 Amazon 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 user stops the alert.
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 the Alerts channel is actively rendering the asset or silent between loops, wait the full duration of loopPauseInMilliSeconds before rendering the background asset. If the Alerts channel regains foreground focus, begin rendering the foreground asset immediately.

Note: If the loopPauseInMilliSeconds value isn't specified, is set to 0, or is shorter than the duration of the asset, there must not be any silence between asset loops.
long

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 a DeleteAlertsSucceeded 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 a DeleteAlertsFailed 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

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

DeleteAlertSucceeded

Send the DeleteAlertSucceeded event to AVS after receiving a DeleteAlert directive, and the client deletes or cancels the specified alert.

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.

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.

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:

  1. The client receives a DeleteAlert directive. After sending an AlertStopped event, your client must inform AVS if it could delete the alert with either a DeleteAlertSucceeded event or DeleteAlertFailed event.
  2. A user uses a physical control (hardware button or GUI) to stop the alert.
  3. The loopCount is complete, or an alert without a loopCount 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