Alerts Interface (Beta)

Note: Submit your skill and see it come to life.

Note: On December 31, 2021, we paused support for third-party device makers working with Alexa Gadgets, while we work to create an even better developer and customer experience. Please stay tuned to the Amazon developer portal for updates. In the interim, please visit the landing pages for Alexa Voice Service, Alexa Connect Kit, and Alexa Skills Kit to discover ways you can provide new customer experiences with voice.

This interface provides directives that instruct your gadget to set a timer, alarm, or reminder for a specific time or duration, or to delete a timer that is set.

Note: Each directive and event is a compilation of three separate .proto files: a header, a payload, and a file that combines the two. You can download the .proto files from the Alexa Gadgets Sample Code GitHub repository. In this topic, the .proto files combine all fields into one file for descriptive purposes.

Supporting this interface
Directives
- SetAlert directive
  - Message definition
  - Field descriptions
- DeleteAlert directive
  - Message definition
  - Field descriptions

Supporting this interface

To support this interface, your gadget must respond to the Echo device's Discover directive with a Discover.Response event that includes the following entry in its array of Capabilities:

{
   "type": "AlexaInterface",
   "interface": "Alerts",
   "version": "1.1"
}

Directives

This interface includes two directives: SetAlert and DeleteAlert, as described next.

SetAlert directive

This directive instructs your gadget to set a timer, alarm, or reminder for a specific time or duration. Your gadget will receive this directive as a result of a speech request to set an alert, when a previously set alert is re-enabled using the Alexa app, or a paused timer is resumed in the Alexa app.

Message definition

This directive is defined by .proto files as follows.

directiveHeader.proto

message DirectiveHeaderProto {
   string namespace = 1;
   string name = 2;
   string messageId = 3;
   string dialogRequestId = 4;
}

alertsSetAlertDirective.proto

message SetAlertDirectiveProto {
   Directive directive = 1;
   message Directive {
      alerts.SetAlertDirectivePayloadProto payload = 2;
      header.DirectiveHeaderProto header = 1;
   }
}

alertsSetAlertDirectivePayload.proto

message SetAlertDirectivePayloadProto {
   repeated string assetPlayOrder = 5;
   int32 loopPauseInMilliSeconds = 8;
   string scheduledTime = 3;
   repeated Assets assets = 4;
   message Assets {
      string assetId = 1;
      string url = 2;
   }
   int32 loopCount = 7;
   string backgroundAlertAsset = 6;
   string type = 2;
   string token = 1;
}

Field descriptions

This directive contains the following fields.

Header fields

Field	Description	Type
`namespace`	The namespace of this directive, which is `Alerts`.	`string`
`name`	The name of this directive, which is `SetAlert`.	`string`
`messageId`	An ID that uniquely defines an instance of this directive. This string can be empty.	`string`
`dialogRequestId`	A unique ID that correlates this directive with a specific voice interaction from a user.	`string`

Payload fields

Of the fields in the following table, your gadget will currently only receive scheduledTime, type, and token.

Field	Description	Type
`token`	An identifier that uniquely identifies the alert.	`string`
`type`	Identifies the alert type. Accepted values: `TIMER`, `ALARM`, and `REMINDER`. If the gadget does not recognize the value, it must default to `ALARM`.	`string`
`scheduledTime`	The scheduled time for an alert in ISO 8601 format.	`string`
`assets`	A list of audio assets that the gadget must play. Each asset has a unique identifier and a URL.	List
`assets.assetId`	A unique identifier for the audio asset.	`string`
`assets.url`	The location of the asset in the cloud. This asset may be downloaded and cached by your gadget. The URL provided is valid for 60 minutes after the `scheduledTime`.	`string`
`assetPlayOrder`	The sequence in which the gadget must play the audio assets. Your gadget must play all assets in the order in which they appear in `assetPlayOrder`. If your gadget fails to download and cache the assets, the gadget should use the audio files that Amazon provides.	List of `string`
`backgroundAlertAsset`	If present, this value will match an `assetId` in the assets list. If `backgroundAlertAsset` is not included in the payload, your gadget must default to the Amazon-provided sound in the Alexa sound library. This is available to download in the developer portal under Alexa Voice Service > Resources.	`string`
`loopCount`	The number of times that each sequence of assets must be played. For example: If the value is 2, your gadget must loop through `assetPlayOrder` two times. If `loopCount` is absent from the payload, you must loop the assets for one hour, or until the user stops the alert.	`int32`
`loopPauseInMilliSeconds`	The pause duration between each asset loop. For example, if `loopPauseInMilliSeconds` is 300 and `loopCount` is 3, your gadget must pause for 300 milliseconds between each asset loop. If this value is not specified or is set to 0, your gadget must not pause between asset loops.	`int32`

DeleteAlert directive

This directive instructs your gadget to delete an existing alert. Your gadget will receive this directive as a result of a speech request to cancel or delete a timer, alarm, or reminder, when a previously set alert is deleted using the Alexa app, or when a timer is paused in the Alexa app.