Alerts Capability Interface
The Alerts capability comprises the mechanics that enable a device to play alerts to the user, including alarms, timers, and reminders.
It defines messages on the directive
and event
topics and depends on the Speaker interface.
Implementing the Alerts capability requires that the device
- saves alerts in persistent storage to support offline playback;
- plays stored or synthesized alert tones; and
- synchronizes its clock periodically, either through the Clock interface or through a separate time source, such as an NTP server
If the device can store an alert tone for offline playback, see the Alexa sound library for AVS for downloadable assets (available in the Alexa Voice Service > Resources section of the Developer Console).
Getting Started
AIA Envelope
This capability interface is compatible with v1
of the AIA envelope.
Topic Management
To support Alerts 1.0 messages, the device must participate in the directive
and event
topics. Because it depends on the Speaker interface, it must also implicitly participate in the speaker
topic.
Capability Assertion
To use the Alerts 1.0 interface, the device must assert support through the Publish
message on the capabilities
topic.
Sample Object
{ "type": "AisInterface", "interface": "Alerts", "version": "1.0", "configurations": { "maxAlertCount": {{LONG}} } }
Field Name | Description | Value Type |
---|---|---|
maxAlertCount |
The maximum number of alerts that the device can store for offline playback. | long |
directive
Topic
SetAlert
The SetAlert
directive instructs the device to store an alert to persistent storage. An alert may be an alarm, a timer, or a reminder.
The device must respond with a SetAlertSucceeded
or SetAlertFailed
event.
If the device is offline at the specified alert time, it must play a stored alert sound or synthesized tone. If the device is online and connected to AIA, it will receive the alert audio through the Speaker interface.
To ensure an optimal user experience, the device must follow the clock synchronization guidance in the Clock
interface. If the device is not already connected to AIA, it must attempt to reconnect 5 minutes prior to the scheduled playback of any locally stored alert, processing any changes to or deletions of previously set alerts.
Sample Message
{ "header": { "name": "SetAlert", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "scheduledTime": {{LONG}}, "durationInMilliseconds": {{LONG}}, "type": "{{STRING}}" } }
Payload Parameters
Field Name | Description | Value Type |
---|---|---|
token |
A unique token identifying the alert, with maximum size of 8 characters. If an alert with this token value is already stored locally, the details in this directive should replace the previously stored details. |
string |
scheduledTime |
The UTC time in seconds since NTP epoch that the alert should be played. Note: NTP epoch is 1900-01-01 00:00:00, which differs from Unix epoch (1970-01-01 00:00:00). |
long |
durationInMilliseconds |
The duration that the stored alert sound or synthesized tone must play, starting at the scheduledTime .
|
long |
type |
The type of the alert, which may be used to manifest different alert tones. Possible Values: ALARM , TIMER , REMINDER
|
string |
DeleteAlert
The DeleteAlert
directive instructs the device to delete an alert previously set in response to a SetAlert
directive.
The device must respond with a DeleteAlertSucceeded
or DeleteAlertFailed
event.
Note: If the device was offline during a scheduled alert and the alert was deleted in that time, AIA will not send the DeleteAlert
directive. The directive is not needed because the device will not report the deleted alert in the SynchronizeState
event's alerts.allAlerts
list when the device reestablishes a connection to AIA.
Sample Message
{ "header": { "name": "DeleteAlert", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" } }
Payload Parameters
Field Name | Description | Value Type |
---|---|---|
token |
A unique token identifying the alert to be deleted, with maximum size of 8 characters. | string |
SetAlertVolume
The SetAlertVolume
directive instructs the device to use the specified volume for manifesting offline alerts set through the SetAlert
directive.
The device must respond with an AlertVolumeChanged
event.
Notes:
- The volume specified in this directive is applicable only to alerts manifesting when the device is offline. If the device is online when an alert plays through the Speaker interface, its volume will be determined by the
SetVolume
directive. - The device must persist the volume level setting across reboots, so that if network connectivity cannot be reestablished when the alert triggers, it will manifest at the correct volume level.
Sample Message
{ "header": { "name": "SetAlertVolume", "messageId": "{{STRING}}" }, "payload": { "volume": {{LONG}} } }
Payload Parameters
Field Name | Description | Value Type |
---|---|---|
volume |
The volume level to apply on a scale of 0 (mute) to 100 (maximum output).
|
long |
event
Topic
SetAlertSucceeded
After receiving the SetAlert
directive, if the device was able to successfully save the alert to persistent local storage, it must send the SetAlertSucceeded
event in response.
Sample Message
{ "header": { "name": "SetAlertSucceeded", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" } }
Payload Parameters
Field Name | Description | Value Type |
---|---|---|
token |
The token identifying the alert that was successfully saved. | string |
SetAlertFailed
After receiving the SetAlert
directive, if the device failed to save the alert to persistent local storage, it must send the SetAlertFailed
event in response.
Sample Message
{ "header": { "name": "SetAlertFailed", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" } }
Payload Parameters
Field Name | Description | Value Type |
---|---|---|
token |
The token identifying the alert that could not be saved. | string |
DeleteAlertSucceeded
After receiving the DeleteAlert
directive, if the device was able to successfully delete the alert from persistent local storage, it must send the DeleteAlertSucceeded
event in response.
Sample Message
{ "header": { "name": "DeleteAlertSucceeded", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" } }
Payload Parameters
Field Name | Description | Value Type |
---|---|---|
token |
The token identifying the alert that was successfully deleted. | string |
DeleteAlertFailed
After receiving the DeleteAlert
directive, if the device failed to delete the alert from persistent local storage, it must send the DeleteAlertFailed
event in response.
Sample Message
{ "header": { "name": "DeleteAlertFailed", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" } }
Payload Parameters
Field Name | Description | Value Type |
---|---|---|
token |
The token identifying the alert that could not be deleted. | string |
AlertVolumeChanged
The device must send the AlertVolumeChanged
event in response to the SetAlertVolume
directive.
This event must always be sent in response to the SetAlertVolume
directive, even if the volume
is the same as the previously set value.
Note: The volume specified in the SetAlertVolume
directive and in this event is applicable only to alerts manifesting when the device is offline. If the device is online when an alert plays through the Speaker interface, its volume will be determined by the SetVolume
directive.
Sample Message
{ "header": { "name": "AlertVolumeChanged", "messageId": "{{STRING}}" }, "payload": { "volume": {{LONG}} } }
Payload Parameters
Field Name | Description | Value Type |
---|---|---|
volume |
The volume level set, on a scale of 0 (mute) to 100 (maximum output).
|
long |