Notifications API

You can use the Alexa Notifications REST API to send notifications to your customers. You can specify either of the following notification types:

  • Device notification – For headless devices like Amazon Echo Dot, this is a yellow ring and a chime sound. For multimodal devices, it's a banner and a persistent notification indicator.
  • Announcement – For headless and multimodal devices, this is a voice announcement. Multimodal devices also display a message on the screen.

Send notifications

Call POST /v3/notifications to send notifications to customers.

Request format

POST /v3/notifications HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body example

{
  "recipients": [
    {
      "type": "Unit",
      "id": "amzn1.alexa.unit.unitId"
    }
  ],
  "notification": {
    "variants": [
      {
        "type": "DeviceNotification",
        "content": {
          "variants": [
            {
              "type": "SpokenText",
              "values": [
                {
                  "locale": "en-US",
                  "text": "Happy hour is starting now in the pool area!"
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Request body parameters

Field Description Type Required
recipients The recipient of the notification. Array Yes
recipients[].type Recipient type: Unit. Enum Yes
recipients[].id "The unit ID, in the format amzn1.alexa.unit.did.{id}." Enum Yes
notification The notification object. Object Yes
notification.variants[].type Notification delivery type: DeviceNotification or Announcement. Enum Yes
notification.variants[].content Notification content helps developers specifying different variants of content for spoken and display purposes. Object Yes
notification.variants[].content.variants[] The locale-specific notification content to be delivered to the end user. Array Yes
notification.variants[].content.variants[].type Type of content. SpokenText, which represents localized text input. Enum Yes
notification.variants[].content.variants[].values[] Content values array. Each element in the array represents localized text input. Array Yes
notification.variants[].content.variants[].values[].locale The locale in which the spoken text is rendered, in IETF BCP 47 format. String Yes
notification.variants[].content.variants[].values[].text Spoken text in plain text format. String Yes

Response header

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type Required
X-Amzn-RequestId Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. String No

Response body

None.

HTTP response codes

Status Code Name Description
202 Accepted The request succeeded.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing, expired, or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
429 Too many requests The request is throttled.
500 Internal Server Error The request couldn't be handled because of an internal service error.
503 Service Unavailable The server is temporarily unavailable.
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment