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