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 |
Last updated: Mar 31, 2022