Alerts Interface

    The Alerts Interface of the Alexa Voice Service (AVS) exposes directives and events that set, manage, and cancel timers, alarms, and reminders. For a user to set an alert, your client must have an active internet connection to receive directives that instruct your client to take action. For example, SetAlert and DeleteAlert and to send events that inform AVS about an event on the client, such as SetAlertSucceeded and DeleteAlertSucceeded.

    See the Alerts Overview and the Interaction Model for more implementation details.

    Version changes

    • The Alerts interface v1.3 allows the deletion of all client alerts via the DeleteAlerts directive, DeleteAlertsFailed event, and DeleteAlertsSucceeded event.
    • The Alerts v1.3 interface includes the SetVolume and AdjustVolume directives, and the VolumeChanged event. The addition of these directives and events enable the user to control alert volume via the Amazon Alexa app.
    • v1.3 supports users selecting custom alert tones within the Amazon Alexa app. See AVS UX Attention System for guidance on how to manage alerts, including custom alerts, for your product.

    Capability assertion

    A device can't implement Alerts 1.3 on behalf of connected endpoints but can implement Alerts 1.3 itself.

    New AVS integrations must assert support through Alexa.Discovery, but AVS continues support for legacy integrations through the Capabilities API.

    Sample Object

    {
        "type": "AlexaInterface",
        "interface": "Alerts",
        "version": "1.3",
        "configurations": {
            "maximumAlerts": {
                "overall": {{INTEGER}},
                "alarms": {{INTEGER}},
                "timers": {{INTEGER}}
            }
        }
    }
    

    Configuration Parameters

    Parameter Description Type
    maximumAlerts An object that contains configuration information for your Alerts implementation. object
    maximumAlerts.overall Maximum total number of timers plus alarms stored on a device at a given time. integer
    maximumAlerts.alarms Maximum number of alarms stored on a device at a given time. integer
    maximumAlerts.timers Maximum number of timers stored on a device at a given time. integer

    Alerts Context

    Alexa expects a client to report the status of all locally stored alerts with each event that requires context. Individual alerts belong to one of two categories: allAlerts and activeAlerts. allAlerts is a complete list of locally stored alerts. activeAlerts is a list of alerts in focus or sounding for a user.

    To learn more about reporting Context, see Context Overview.

    Sample message

    {
        "header": {
            "namespace": "Alerts",
            "name": "AlertsState"
        },
        "payload": {
            "allAlerts": [
                {
                    "token": "{{STRING}}",
                    "type": "{{STRING}}",
                    "scheduledTime": "{{STRING}}"
                }
            ],
            "activeAlerts": [
                {
                    "token": "{{STRING}}",
                    "type": "{{STRING}}",
                    "scheduledTime": "{{STRING}}"
                }
            ]
        }
    }
    

    Payload parameters

    Parameter Description Type
    allAlerts Key/value pairs for allAlerts object
    allAlerts.token Alert token returned by Alexa when the user sets the alert. string
    allAlerts.type Identifies the alert type.
    Accepted Values: TIMER, ALARM, REMINDER.
    string
    allAlerts.scheduledTime Timestamp for when the alert is scheduled, in YYYY-MM-DDThh:mm:ss±hhmm ISO 8601 format.
    Example value: "2018-11-28T09:34:32+0000"
    string
    activeAlerts Key/value pairs for activeAlerts object
    activeAlerts.token The token for the alert current active alert. string
    activeAlerts.type Identifies the alert type.
    Accepted Values: TIMER or ALARM
    string
    activeAlerts.scheduledTime Timestamp for when the alert is scheduled, in YYYY-MM-DDThh:mm:ss±hhmm ISO 8601 format.
    Example value: "2018-11-28T09:34:32+0000"
    string

    SetAlert directive

    The SetAlert directive instructs your client to set a timer, alarm, or reminder for a specific duration or time. Clients receive the SetAlert directive when a user makes a speech request to set or re-enable an alert via the Amazon Alexa app.

    If loopCount is absent from the payload, the alert must sound for one hour or until stops the alert with a voice request or physically interacting with the client.

    AVS-provided assets take precedence over locally stored audio files. If the AVS cloud provides assets, the client must play them for the user in the order provided in the assetPlayOrder list. Otherwise, use the audio files for alerts provided by Amazon.

    Sample message

    {
        "directive": {
            "header": {
                "namespace": "Alerts",
                "name": "SetAlert",
                "messageId": "{{STRING}}",
                "dialogRequestId": "{{STRING}}"
            },
            "payload": {
                "token": "{{STRING}}",
                "type": "{{STRING}}",
                "scheduledTime": "{{STRING}}",
                "assets": [
                    {
                        "assetId": "{{STRING}}",
                        "url": "{{STRING}}"
                    },
                    {
                        "assetId": "{{STRING}}",
                        "url": "{{STRING}}"
                    },
                ],
                "assetPlayOrder": [ {{LIST}} ],
                "backgroundAlertAsset": "{{STRING}}",
                "loopCount": {{LONG}},
                "loopPauseInMilliSeconds": {{LONG}}
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string
    dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

    Payload parameters

    Parameter Description Type
    token An opaque token that uniquely identifies the alert. string
    type Identifies the alert type. If an unrecognized value is sent to your client, it should default to an ALARM.
    Accepted values: TIMER, ALARM, REMINDER.
    string
    scheduledTime Timestamp for when the alert is scheduled, in YYYY-MM-DDThh:mm:ss±hhmm ISO 8601 format.
    Example value: "2018-11-28T09:34:32+0000"
    string
    assets List containing audio assets to play for the user. list
    assets[i].assetId A unique identifier for the audio asset. string
    assets[i].url Identifies the location of the asset in the cloud for the client to download and cache. The URL provided is valid for 60 minutes after the scheduledTime. string
    assetPlayOrder The sequence that audio assets must be played. The list contains assetIds.

    Note: assetIds might appear more than one time in the list, which must all be played. If your client fails to download and cache the assets, your device should use the audio files provided by Amazon.
    list
    backgroundAlertAsset If present, the backgroundAlertAsset value matches an assetId in the assets list. If backgroundAlertAsset is not included in the payload, default to the Amazon provided sound in the Alexa sound library for AVS, which is available to download in the Alexa Voice Service > Resources section of the Amazon developer console. string
    loopCount The number of times each sequence of assets must be played. For example: If the value is 2, your client must loop through assetPlayOrder two times.

    Note: If loopCount is absent from the payload, you must loop the assets for one hour, or until the user stops the alert.
    long
    loopPauseInMilliSeconds Duration between the beginnings of each asset loop, which includes the asset rendering time. For example, if a single alarm sound has a 200-millisecond duration and loopPauseInMilliSeconds is 700, assuming loopCount is greater than 1, your client must render 500 milliseconds of silence between the end of one instance of the alarm sound and the beginning of the next.

    If the Alerts channel is sent to the background, regardless of whether the Alerts channel is actively rendering the asset or silent between loops, wait the full duration of loopPauseInMilliSeconds before rendering the background asset. If the Alerts channel regains foreground focus, begin rendering the foreground asset immediately.

    Note: If the loopPauseInMilliSeconds value is not specified, is set to 0, or is shorter than the duration of the asset, there must not be any silence between asset loops.
    long

    SetAlertSucceeded event

    Send the SetAlertSucceeded event to AVS after receiving a SetAlert directive and setting the alert on the client.

    {
        "event": {
            "header": {
                "namespace": "Alerts",
                "name": "SetAlertSucceeded",
                "messageId": "{{STRING}}"
            },
            "payload": {
                "token": "{{STRING}}"
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    Parameter Description Type
    token An opaque token provided by the SetAlert directive. string

    SetAlertFailed event

    Send the SetAlertFailed event to AVS after receiving a SetAlert directive and failing to set the alert on the client.

    Sample message

    {
        "event": {
            "header": {
                "namespace": "Alerts",
                "name": "SetAlertFailed",
                "messageId": "{{STRING}}"
            },
            "payload": {
                "token": "{{STRING}}"
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    Parameter Description Type
    token An opaque token provided by the SetAlert directive. string

    DeleteAlert directive

    AVS sends a DeleteAlert directive to the client to delete an existing alert. The client receives the DeleteAlert directive when a user makes a speech request to cancel or delete a timer, alarm, or reminder, or deletes an existing set alert using the Amazon Alexa app.

    Sample message

    {
        "directive": {
            "header": {
                "namespace": "Alerts",
                "name": "DeleteAlert",
                "messageId": "{{STRING}}",
                "dialogRequestId": "{{STRING}}"
            },
            "payload": {
                "token": "{{STRING}}"
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string
    dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

    Payload parameters

    Parameter Description Type
    token An opaque token that uniquely identifies the alert. string

    DeleteAlertSucceeded event

    Send the DeleteAlertSucceeded event to AVS after receiving a DeleteAlert directive, and the client deletes or cancels the specified alert.

    Sample message

    {
        "event": {
            "header": {
                "namespace": "Alerts",
                "name": "DeleteAlertSucceeded",
                "messageId": "{{STRING}}"
            },
            "payload": {
                "token": "{{STRING}}"
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    Parameter Description Type
    token An opaque token provided by the DeleteAlert directive. string

    DeleteAlertFailed event

    Send the DeleteAlertFailed event to AVS after the client receives a DeleteAlert directive, but fails to delete or cancel the specified alert.

    Sample message

    {
        "event": {
            "header": {
                "namespace": "Alerts",
                "name": "DeleteAlertFailed",
                "messageId": "{{STRING}}"
            },
            "payload": {
                "token": "{{STRING}}"
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    Parameter Description Type
    token An opaque token provided by the DeleteAlert directive. string

    DeleteAlerts directive

    The DeleteAlerts directive instructs a client to delete all its existing alerts. A client receives the DeleteAlerts directive when a user makes a speech request to cancel/delete all alerts. Use the tokens array to group the identifiers for individual alerts.

    • After deleting all alerts found in the tokens array on the client, send a DeleteAlertsSucceeded event to AVS.
    • If the client is unable to actually delete any alerts found on the client that are present in the tokens array, send a DeleteAlertsFailed event to AVS.

    Sample message

    {
        "directive": {
            "header": {
                "namespace": "Alerts",
                "name": "DeleteAlerts",
                "messageId": "{{STRING}}"
            },
            "payload": {
                "tokens": ["{{STRING}}",...]
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string
    dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

    Payload parameters

    Parameter Description Type
    tokens An array of tokens. Each token is a string that uniquely represents an alert on the product. string

    DeleteAlertsSucceeded event

    Send the DeleteAlertsSucceeded event to AVS after receiving a DeleteAlerts directive, after the client deletes or cancels all existing alerts within the tokens array.

    For more information about when to send the DeleteAlertsSucceeded event, see Alerts Overview.

    Sample message

    {
        "event": {
            "header": {
                "namespace": "Alerts",
                "name": "DeleteAlertsSucceeded",
                "messageId": "{{STRING}}"
            },
            "payload": {
                "tokens": ["{{STRING}}",...]
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    Parameter Description Type
    tokens An array of tokens. Each token is a string that uniquely represents an alert on the client. string

    DeleteAlertsFailed event

    Send a DeleteAlertsFailed event to AVS after receiving a DeleteAlerts directive, if the client is able to find but fails to delete or cancel at least one of the existing alerts within the tokens array.

    If the client fails to delete one or more alerts, the client must rollback and send a DeleteAlertsFailed event to Alexa. Alexa then retries the request until the client is able to delete all alerts and then sends a DeleteAlertsSucceeded event to AVS.

    For more information about when to send the DeleteAlertsFailed event, see Alerts Overview.

    Sample message

    {
        "event": {
            "header": {
                "namespace": "Alerts",
                "name": "DeleteAlertsFailed",
                "messageId": "{{STRING}}"
            },
            "payload": {
                "tokens": ["{{STRING}}",...]
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    Parameter Description Type
    tokens An array of tokens. Each token is a string that uniquely represents an alert on the product. string

    AlertStarted event

    Send the AlertStarted event to AVS when an alert starts at its scheduled time.

    For more information about when to send the AlertStarted event, see Alerts Overview.

    Sample message

    {
        "event": {
            "header": {
                "namespace": "Alerts",
                "name": "AlertStarted",
                "messageId": "{{STRING}}"
            },
            "payload": {
                "token": "{{STRING}}"
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    Parameter Description Type
    token An opaque token provided by the SetAlert directive. string

    AlertStopped event

    Send the AlertStopped event to AVS when an active alert ends for any of the following reasons:

    1. The client receives a DeleteAlert directive. After sending an AlertStopped event, your client must inform AVS if it could delete the alert with either a DeleteAlertSucceeded event or DeleteAlertFailed event.
    2. A user uses a physical control (hardware button or GUI) to stop the alert.
    3. The loopCount is complete, or an alert without a loopCount has played for one hour on the client.

    See Alerts Overview for more information about sending AlertStopped.

    Sample message

    {
        "event": {
            "header": {
                "namespace": "Alerts",
                "name": "AlertStopped",
                "messageId": "{STRING}"
            },
            "payload": {
                "token": "{{STRING}}"
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    Parameter Description Type
    token An opaque token provided by the SetAlert directive. string

    AlertEnteredForeground event

    A client sends the AlertEnteredForeground event to AVS when an active alert enters the foreground by playing at full volume or re-enters the foreground after a concurrent interaction on the Dialog channel completes. For specific details on channel interaction, see Interaction Model.

    Sample message

    {
        "event": {
            "header": {
                "namespace": "Alerts",
                "name": "AlertEnteredForeground",
                "messageId": "{{STRING}}"
            },
            "payload": {
                "token": "{{STRING}}"
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    Parameter Description Type
    token An opaque token provided by the SetAlert directive. string

    AlertEnteredBackground event

    The client sends the AlertEnteredBackground event to AVS when an active alert exits the foreground by attenuating or pausing, while a concurrent interaction on the Dialog channel is occurring. For specific details on channel interaction, see Interaction Model.

    Sample message

    {
        "event": {
            "header": {
                "namespace": "Alerts",
                "name": "AlertEnteredBackground",
                "messageId": "{{STRING}}"
            },
            "payload": {
                "token": "{{STRING}}"
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    Parameter Description Type
    token An opaque token provided in the SetAlert directive. string

    SetVolume directive

    The SetVolume directive instructs a client to set the absolute volume level for an alert.

    Sample message

    {
        "directive": {
            "header": {
                "namespace": "Alerts",
                "name": "SetVolume",
                "messageId": "{{STRING}}",
                "dialogRequestId": {{STRING}}
            },
            "payload": {
                "volume": "{{LONG}}"
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string
    dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

    Payload parameters

    Parameter Description Type
    volume The absolute volume level scaled from a minimum of 0 min to a maximum of 100.
    Accepted values: Any value between 0 and 100, inclusive.
    long

    AdjustVolume directive

    The AdjustVolume directive instructs a client to adjust the relative volume level of an alert.

    Sample message

    {
        "directive": {
            "header": {
                "namespace": "Alerts",
                "name": "AdjustVolume",
                "messageId": "{{STRING}}",
                "dialogRequestId": {{STRING}}
            },
            "payload": {
                "volume": "{{LONG}}"
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string
    dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

    Payload parameters

    Parameter Description Type
    volume The relative volume adjustment. A positive or negative long value that increases or decreases volume in relation to the current volume setting.
    Accepted values: Any value between -100 and 100, inclusive.
    long

    VolumeChanged event

    The client sends a VolumeChanged event to AVS after receiving either a SetVolume or AdjustVolume directive.

    Sample message

    {
        "event": {
            "header": {
                "namespace": "Alerts",
                "name": "VolumeChanged",
                "messageId": "{{STRING}}"
            },
            "payload": {
                "volume": "{{LONG}}"
            }
        }
    }
    

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    Parameter Description Type
    volume The locally adjusted the volume on the client.
    Accepted values: Volume must be a value between 0 and 100, inclusive.
    Important: If the client supports a volume range from 0 to 10, map the local range to a range of 0 to 100. For example, when the user locally increases the volume to 8, AVS expects the volume value sent to be 80.
    long

      The Alerts Interface of the Alexa Voice Service (AVS) exposes directives and events that set, manage, and cancel timers, alarms, and reminders. For a user to set an alert, your client must have an active internet connection to receive directives that instruct your client to take action.

      See the Alerts Overview and the Interaction Model for more implementation details.

      Version changes

      • The payload of the SetAlert directive now supports named timers and reminders. This change is backward compatible.

      Capability assertion

      Alerts 1.1 may be implemented by the device on its own behalf, but not on behalf of any connected endpoints.

      New AVS integrations must assert support through Alexa.Discovery, but AVS continues support for legacy integrations through the Capabilities API.

      Sample Object

      {
          "type": "AlexaInterface",
          "interface": "Alerts",
          "version": "1.1",
          "configurations": {
              "maximumAlerts": {
                  "overall": {{INTEGER}},
                  "alarms": {{INTEGER}},
                  "timers": {{INTEGER}}
              }
          }
      }
      

      Configuration Parameters

      Parameter Description Type
      maximumAlerts An object that contains configuration information for your Alerts implementation. object
      maximumAlerts.overall The maximum number of combined alerts (timers and alarms) your product can store at a given time. integer
      maximumAlerts.alarms The maximum number of alarms your product can store at a given time. integer
      maximumAlerts.timers The maximum number of timers your product can store at a given time. integer

      Alerts Context

      Alexa expects a client to report the status of all locally stored alerts with each event that requires context. Alerts are organized into two lists: allAlerts and activeAlerts. allAlerts is a complete list of locally stored alerts. activeAlerts is a list of alerts currently in focus or sounding for an end user.

      To learn more about reporting Context, see Context Overview.

      Sample Message

      {
          "header": {
              "namespace": "Alerts",
              "name": "AlertsState"
          },
          "payload": {
              "allAlerts": [
                  {
                      "token": "{{STRING}}",
                      "type": "{{STRING}}",
                      "scheduledTime": "{{STRING}}"
                  }
              ],
              "activeAlerts": [
                  {
                      "token": "{{STRING}}",
                      "type": "{{STRING}}",
                      "scheduledTime": "{{STRING}}"
                  }
              ]
          }
      }
      

      Payload Parameters

      Parameter Description Type
      allAlerts Key/value pairs for allAlerts object
      allAlerts.token Alert token returned by Alexa when the alert was set. string
      allAlerts.type Identifies the alert type.
      Accepted Values: TIMER, ALARM, REMINDER.
      string
      allAlerts.scheduledTime Timestamp for when the alert is scheduled in YYYY-MM-DDThh:mm:ss±hhmm ISO 8601 format.
      Example value: "2018-11-28T09:34:32+0000"
      string
      activeAlerts Key/value pairs for activeAlerts object
      activeAlerts.token The token for the alert that is currently firing. string
      activeAlerts.type Identifies the alert type.
      Accepted Values: TIMER or ALARM
      string
      activeAlerts.scheduledTime Timestamp for when the alert is scheduled in YYYY-MM-DDThh:mm:ss±hhmm ISO 8601 format.
      Example value: "2018-11-28T09:34:32+0000"
      string

      SetAlert Directive

      This directive instructs your client to set a timer, alarm, or reminder for a specific duration or time. Your client may receive the SetAlert directive as a result of a speech request to set an alert, or when a previously set alert is re-enabled using the Amazon Alexa app.

      If loopCount is absent from the payload, the alert must sound for one hour or until it is stopped by the user (voice request or physical affordance).

      Cloud provided assets take precedence over locally stored audio files. If assets are provided they must be played for the user in the order provided in the assetPlayOrder list. Otherwise, use the audio files for alerts provided by Amazon.

      Sample Message

      {
          "directive": {
              "header": {
                  "namespace": "Alerts",
                  "name": "SetAlert",
                  "messageId": "{{STRING}}",
                  "dialogRequestId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}",
                  "type": "{{STRING}}",
                  "scheduledTime": "{{STRING}}",
                  "assets": [
                      {
                          "assetId": "{{STRING}}",
                          "url": "{{STRING}}"
                      },
                      {
                          "assetId": "{{STRING}}",
                          "url": "{{STRING}}"
                      },
                  ],
                  "assetPlayOrder": [ {{LIST}} ],
                  "backgroundAlertAsset": "{{STRING}}",
                  "loopCount": {{LONG}},
                  "loopPauseInMilliSeconds": {{LONG}}
              }
          }
      }
      

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string
      dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

      Payload Parameters

      Parameter Description Type
      token An opaque token that uniquely identifies the alert. string
      type Identifies the alert type. If an unrecognized value is sent to your client, it should default to an ALARM.
      Accepted values: TIMER, ALARM, REMINDER.
      string
      scheduledTime Timestamp for when the alert is scheduled in YYYY-MM-DDThh:mm:ss±hhmm ISO 8601 format.
      Example value: "2018-11-28T09:34:32+0000"
      string
      assets A list that contains audio assets to be played to the user. list
      assets[i].assetId A unique identifier for the audio asset. string
      assets[i].url Identifies the location of the asset in the cloud. This asset may be downloaded and cached by your client. The URL provided is valid for 60 minutes after the scheduledTime. string
      assetPlayOrder The sequence that audio assets must be played. The list is comprised of assetIds.

      Note: i) assetIds may appear multiple times in the list. When this occurs, all assetIds must be played. ii) If your client fails to download and cache the assets, your device should use the audio files provided by Amazon.
      list
      backgroundAlertAsset If present, the backgroundAlertAsset value will match an assetId in the assets list. If backgroundAlertAsset is not included in the payload, default to the Amazon provided sound in the Alexa sound library for AVS, which is available to download in the Alexa Voice Service > Resources section of the Developer Console. string
      loopCount The number of times each sequence of assets must be played. For example: If the value is 2, your client must loop through assetPlayOrder two times.

      Note: If loopCount is absent from the payload, you must loop the assets for one hour, or until the alert is stopped by the user.
      long
      loopPauseInMilliSeconds Duration between the beginnings of each asset loop, which includes the asset rendering time. For example: If a single alarm sound has a 200-millisecond duration and loopPauseInMilliSeconds is 700, assuming loopCount is greater than 1, your client must render 500 milliseconds of silence between the end of one instance of the alarm sound and the beginning of the next.

      If the Alerts channel is sent to the background (regardless of whether it is currently rendering the asset or silent between loops), wait the full duration of loopPauseInMilliSeconds before rendering the background asset. If it regains foreground focus, begin rendering the foreground asset immediately.

      Note: If this value is not specified, is set to 0, or is shorter than the duration of the asset, there must not be any silence between asset loops.
      long

      SetAlertSucceeded Event

      The SetAlertSucceeded event must be sent to AVS after receiving a SetAlert directive, when the client successfully sets the alert.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "Alerts",
                  "name": "SetAlertSucceeded",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}"
              }
          }
      }
      

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string

      Payload Parameters

      Parameter Description Type
      token An opaque token provided by the SetAlert directive. string

      SetAlertFailed Event

      The SetAlertFailed event must be sent to AVS after receiving a SetAlert directive, when the client fails to sets an alert.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "Alerts",
                  "name": "SetAlertFailed",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}"
              }
          }
      }
      

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string

      Payload Parameters

      Parameter Description Type
      token An opaque token provided by the SetAlert directive. string

      DeleteAlert Directive

      This directive is sent from AVS instructing your client to delete an existing alert. Your client may receive the DeleteAlert directive as a result of a speech request to cancel/delete a timer, alarm, or reminder, or when a previously set alert is deleted using the Amazon Alexa app.

      Sample Message

      {
          "directive": {
              "header": {
                  "namespace": "Alerts",
                  "name": "DeleteAlert",
                  "messageId": "{{STRING}}",
                  "dialogRequestId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}"
              }
          }
      }
      

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string
      dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

      Payload Parameters

      Parameter Description Type
      token An opaque token that uniquely identifies the alert. string

      DeleteAlertSucceeded Event

      The DeleteAlertSucceeded event must be sent to AVS after receiving a DeleteAlert directive, when the client successfully deletes or cancels an existing alert.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "Alerts",
                  "name": "DeleteAlertSucceeded",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}"
              }
          }
      }
      

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string

      Payload Parameters

      Parameter Description Type
      token An opaque token provided by the DeleteAlert directive. string

      DeleteAlertFailed Event

      The DeleteAlertFailed event must be sent to AVS after receiving a DeleteAlert directive, when the client fails to delete or cancel an existing alert.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "Alerts",
                  "name": "DeleteAlertFailed",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}"
              }
          }
      }
      

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string

      Payload Parameters

      Parameter Description Type
      token An opaque token provided by the DeleteAlert directive. string

      AlertStarted Event

      The AlertStarted event must be sent to AVS when an alert is triggered at its scheduled time.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "Alerts",
                  "name": "AlertStarted",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}"
              }
          }
      }
      

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string

      Payload Parameters

      Parameter Description Type
      token An opaque token provided by the SetAlert directive. string

      AlertStopped Event

      The AlertStopped event must be sent to AVS when an active alert is stopped. An alert is stopped when:

      1. A DeleteAlert directive is received. After sending an AlertStopped event, your client must inform AVS if the alert was successfully deleted with either a DeleteAlertSucceeded event or DeleteAlertFailed event. This interaction is illustrated in Alerts Overview.
      2. A physical control (hardware button or GUI) is used to stop the alert.
      3. The loopCount is complete, or an alert without a loopCount has played for an hour and is stopped locally.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "Alerts",
                  "name": "AlertStopped",
                  "messageId": "{STRING}"
              },
              "payload": {
                  "token": "{{STRING}}"
              }
          }
      }
      

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string

      Payload Parameters

      Parameter Description Type
      token An opaque token provided by the SetAlert directive. string

      AlertEnteredForeground Event

      The AlertEnteredForeground event must be sent from your client to AVS when an active alert enters the foreground (plays at full volume) or re-enters the foreground after a concurrent interaction on the Dialog channel finishes. For specific details on channel interaction, see Interaction Model.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "Alerts",
                  "name": "AlertEnteredForeground",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}"
              }
          }
      }
      

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string

      Payload Parameters

      Parameter Description Type
      token An opaque token provided by the SetAlert directive. string

      AlertEnteredBackground Event

      The AlertEnteredBackground event must be sent from your client to AVS when an active alert exits the foreground (attenuates or pauses) while a concurrent interaction on the Dialog channel is occurring. For specific details on channel interaction, see Interaction Model.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "Alerts",
                  "name": "AlertEnteredBackground",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}"
              }
          }
      }
      

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string

      Payload Parameters

      Parameter Description Type
      token An opaque token provided in the SetAlert directive. string

        The Alerts Interface of the Alexa Voice Service (AVS) exposes directives and events that set, manage, and cancel timers, alarms, and reminders. For a user to set an alert, your client must have an active internet connection to receive directives that instruct your client to take action.

        See the Alerts Overview and the Interaction Model for more implementation details.

        Capability Assertion

        Alerts 1.0 may be implemented by the device on its own behalf, but not on behalf of any connected endpoints.

        New AVS integrations must assert support through Alexa.Discovery, but AVS continues support for legacy integrations through the Capabilities API.

        Sample Object

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

        Alerts Context

        Alexa expects a client to report the status of all locally stored alerts with each event that requires context. Alerts are organized into two lists: allAlerts and activeAlerts. allAlerts is a complete list of locally stored alerts. activeAlerts is a list of alerts currently in focus or sounding for an end user.

        To learn more about reporting Context, see Context Overview.

        Sample Message

        {
            "header": {
                "namespace": "Alerts",
                "name": "AlertsState"
            },
            "payload": {
                "allAlerts": [
                    {
                        "token": "{{STRING}}",
                        "type": "{{STRING}}",
                        "scheduledTime": "{{STRING}}"
                    }
                ],
                "activeAlerts": [
                    {
                        "token": "{{STRING}}",
                        "type": "{{STRING}}",
                        "scheduledTime": "{{STRING}}"
                    }
                ]
            }
        }
        

        Payload Parameters

        Parameter Description Type
        allAlerts Key/value pairs for allAlerts object
        allAlerts.token Alert token returned by Alexa when the alert was set. string
        allAlerts.type Identifies the alert type.
        Accepted Values: TIMER, ALARM, REMINDER.
        string
        allAlerts.scheduledTime Timestamp for when the alert is scheduled in YYYY-MM-DDThh:mm:ss±hhmm ISO 8601 format.
        Example value: "2018-11-28T09:34:32+0000"
        string
        activeAlerts Key/value pairs for activeAlerts object
        activeAlerts.token The token for the alert that is currently firing. string
        activeAlerts.type Identifies the alert type.
        Accepted Values: TIMER or ALARM
        string
        activeAlerts.scheduledTime Timestamp for when the alert is scheduled in YYYY-MM-DDThh:mm:ss±hhmm ISO 8601 format.
        Example value: "2018-11-28T09:34:32+0000"
        string

        SetAlert Directive

        This directive instructs your client to set a timer or alarm for a specific duration or time. Your client may receive the SetAlert directive as a result of a speech request to set an alert, or when a previously set alert is re-enabled using the Amazon Alexa app.

        Sample Message

        {
            "directive": {
                "header": {
                    "namespace": "Alerts",
                    "name": "SetAlert",
                    "messageId": "{{STRING}}",
                    "dialogRequestId": "{{STRING}}"
                },
                "payload": {
                    "token": "{{STRING}}",
                    "type": "{{STRING}}",
                    "scheduledTime": "{{STRING}}"
                }
            }
        }
        

        Header Parameters

        Parameter Description Type
        messageId A unique ID used to represent a specific message. string
        dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

        Payload Parameters

        Parameter Description Type
        token An opaque token that uniquely identifies the alert. string
        type Identifies the alert type. If an unrecognized value is sent to your client, it should default to an ALARM.
        Accepted values: TIMER, ALARM.
        string
        scheduledTime Timestamp for when the alert is scheduled in YYYY-MM-DDThh:mm:ss±hhmm ISO 8601 format.
        Example value: "2018-11-28T09:34:32+0000"
        string

        SetAlertSucceeded Event

        The SetAlertSucceeded event must be sent to AVS after receiving a SetAlert directive, when the client successfully sets the alert.

        Sample Message

        {
            "event": {
                "header": {
                    "namespace": "Alerts",
                    "name": "SetAlertSucceeded",
                    "messageId": "{{STRING}}"
                },
                "payload": {
                    "token": "{{STRING}}"
                }
            }
        }
        

        Header Parameters

        Parameter Description Type
        messageId A unique ID used to represent a specific message. string

        Payload Parameters

        Parameter Description Type
        token An opaque token provided by the SetAlert directive. string

        SetAlertFailed Event

        The SetAlertFailed event must be sent to AVS after receiving a SetAlert directive, when the client fails to sets an alert.

        Sample Message

        {
            "event": {
                "header": {
                    "namespace": "Alerts",
                    "name": "SetAlertFailed",
                    "messageId": "{{STRING}}"
                },
                "payload": {
                    "token": "{{STRING}}"
                }
            }
        }
        

        Header Parameters

        Parameter Description Type
        messageId A unique ID used to represent a specific message. string

        Payload Parameters

        Parameter Description Type
        token An opaque token provided by the SetAlert directive. string

        DeleteAlert Directive

        This directive is sent from AVS instructing your client to delete an existing alert. Your client may receive the DeleteAlert directive as a result of a speech request to cancel/delete a timer or alarm or when a previously set alert is deleted using the Amazon Alexa app.

        Sample Message

        {
            "directive": {
                "header": {
                    "namespace": "Alerts",
                    "name": "DeleteAlert",
                    "messageId": "{{STRING}}",
                    "dialogRequestId": "{{STRING}}"
                },
                "payload": {
                    "token": "{{STRING}}"
                }
            }
        }
        

        Header Parameters

        Parameter Description Type
        messageId A unique ID used to represent a specific message. string
        dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

        Payload Parameters

        Parameter Description Type
        token An opaque token that uniquely identifies the alert. string

        DeleteAlertSucceeded Event

        The DeleteAlertSucceeded event must be sent to AVS after receiving a DeleteAlert directive, when the client successfully deletes or cancels an existing alert.

        Sample Message

        {
            "event": {
                "header": {
                    "namespace": "Alerts",
                    "name": "DeleteAlertSucceeded",
                    "messageId": "{{STRING}}"
                },
                "payload": {
                    "token": "{{STRING}}"
                }
            }
        }
        

        Header Parameters

        Parameter Description Type
        messageId A unique ID used to represent a specific message. string

        Payload Parameters

        Parameter Description Type
        token An opaque token provided by the DeleteAlert directive. string

        DeleteAlertFailed Event

        The DeleteAlertFailed event must be sent to AVS after receiving a DeleteAlert directive, when the client fails to delete or cancel an existing alert.

        Sample Message

        {
            "event": {
                "header": {
                    "namespace": "Alerts",
                    "name": "DeleteAlertFailed",
                    "messageId": "{{STRING}}"
                },
                "payload": {
                    "token": "{{STRING}}"
                }
            }
        }
        

        Header Parameters

        Parameter Description Type
        messageId A unique ID used to represent a specific message. string

        Payload Parameters

        Parameter Description Type
        token An opaque token provided by the DeleteAlert directive. string

        AlertStarted Event

        The AlertStarted event must be sent to AVS when an alert is triggered at its scheduled time.

        Sample Message

        {
            "event": {
                "header": {
                    "namespace": "Alerts",
                    "name": "AlertStarted",
                    "messageId": "{{STRING}}"
                },
                "payload": {
                    "token": "{{STRING}}"
                }
            }
        }
        

        Header Parameters

        Parameter Description Type
        messageId A unique ID used to represent a specific message. string

        Payload Parameters

        Parameter Description Type
        token An opaque token provided by the SetAlert directive. string

        AlertStopped Event

        The AlertStopped event must be sent to AVS when an active alert is stopped. An alert is stopped when:

        1. A DeleteAlert directive is received. After sending an AlertStopped event, your client must inform AVS if the alert was successfully deleted with either a DeleteAlertSucceeded event or DeleteAlertFailed event. This interaction is illustrated in Alerts Overview.
        2. A physical control (hardware button or GUI) is used to stop the alert.
        3. The loopCount is complete, or an alert without a loopCount has played for an hour and is stopped locally.

        Sample Message

        {
            "event": {
                "header": {
                    "namespace": "Alerts",
                    "name": "AlertStopped",
                    "messageId": "{STRING}"
                },
                "payload": {
                    "token": "{{STRING}}"
                }
            }
        }
        

        Header Parameters

        Parameter Description Type
        messageId A unique ID used to represent a specific message. string

        Payload Parameters

        Parameter Description Type
        token An opaque token provided by the SetAlert directive. string

        AlertEnteredForeground Event

        The AlertEnteredForeground event must be sent from your client to AVS when an active alert enters the foreground (plays at full volume) or re-enters the foreground after a concurrent interaction on the Dialog channel finishes. For specific details on channel interaction, see Interaction Model.

        Sample Message

        {
            "event": {
                "header": {
                    "namespace": "Alerts",
                    "name": "AlertEnteredForeground",
                    "messageId": "{{STRING}}"
                },
                "payload": {
                    "token": "{{STRING}}"
                }
            }
        }
        

        Header Parameters

        Parameter Description Type
        messageId A unique ID used to represent a specific message. string

        Payload Parameters

        Parameter Description Type
        token An opaque token provided by the SetAlert directive. string

        AlertEnteredBackground Event

        The AlertEnteredBackground event must be sent from your client to AVS when an active alert exits the foreground (attenuates or pauses) while a concurrent interaction on the Dialog channel is occurring. For specific details on channel interaction, see Interaction Model.

        Sample Message

        {
            "event": {
                "header": {
                    "namespace": "Alerts",
                    "name": "AlertEnteredBackground",
                    "messageId": "{{STRING}}"
                },
                "payload": {
                    "token": "{{STRING}}"
                }
            }
        }
        

        Header Parameters

        Parameter Description Type
        messageId A unique ID used to represent a specific message. string

        Payload Parameters

        Parameter Description Type
        token An opaque token provided in the SetAlert directive. string