Alerts Interface (Beta)

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.

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.

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

alertsDeleteAlertDirective.proto

message DeleteAlertDirectiveProto {
   Directive directive = 1;
   message Directive {
      alerts.DeleteAlertDirectivePayloadProto payload = 2;
      header.DirectiveHeaderProto header = 1;
   }
}

alertsDeleteAlertDirectivePayload.proto

message DeleteAlertDirectivePayloadProto {
   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 DeleteAlert. 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

Field Description Type
token An identifier that uniquely identifies the alert to cancel. string
Was this page helpful?

Last updated: Mar 31, 2022