Notifications API

Notification types

You can use the Alexa Notifications REST API to send notifications to your customers. Delivers notification to up to a hundred different customers/units in single request. 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.
  • PersistentVisualAlert – For multimodal devices only. This a persistent notification that's displayed on the screen until it expires or the guest or resident dismisses it.

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 examples

The following example shows a device notification.

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

The following example shows an announcement.

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

The following example shows a persistent visual alert.

{
    "recipients": [
      {
        "type": "Unit",
        "id": "amzn1.alexa.unit.did.{unitId1}"
      },
      {
        "type": "Unit",
        "id": "amzn1.alexa.unit.did.{unitId2}"
      },
      {
        "type": "Unit",
        "id": "amzn1.alexa.unit.did.{unitId3}"
      },
      {
        "type": "Unit",
        "id": "amzn1.alexa.unit.did.{unitId4}"
      }
    ],
    "notification": {
        "variants": [{
            "type": "PersistentVisualAlert",
            "content": {
                "variants": [{
                    "type": "V0Template",
                    "values": [{
                        "locale": "en-US",
                        "document": {
                            "type": "Link",
                            "src": "doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/defaultTemplate"
                        },
                        "datasources": {
                            "displayText": {
                                "title": "Light and warm patio breakfast",
                                "body": "Breakfast is served until 11:30 am!"
                            }
                        }
                    }]
                }]
            },
            "dismissalTime": "2021-04-30T10:00:00.00Z"
        }],
        "referenceId": "595973fd-5b66-4970-9401-53f19142aa48"
    }
}

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.{unitId}". String Yes
notification The notification object. Object Yes
notification.variants[].type Notification delivery type: DeviceNotification, Announcement, or PersistentVisualAlert. See Notification types. 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 (for DeviceNotification and Announcement delivery types) or V0Template (for PersistentVisualAlert delivery type). SpokenText represents localized text input. V0Template contains data needed to render a notification using an APL document. An APL document is a JSON object that defines a template to display on a device with a screen. The APL document controls the structure and layout. 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. Maximum length is 1024 characters or 2048 bytes. String Yes
notification.variants[].content.variants[].values[].document For PersistentVisualAlert notifications, this is an APL document to use for rendering the notification. For details, see Use a linked document with RenderDocument. Object Yes, for PersistentVisualAlert notifications
notification.variants[].content.variants[].values[].document.type For PersistentVisualAlert notifications, this is the APL document type. Must be Link. String Yes, for PersistentVisualAlert notifications
notification.variants[].content.variants[].values[].document.src For PersistentVisualAlert notifications, this is the APL document link. Currently only "doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/defaultTemplate" is supported. String Yes, for PersistentVisualAlert notifications
notification.variants[].content.variants[].values[].datasources For PersistentVisualAlert notifications, this is the APL document data. Object Yes, for PersistentVisualAlert notifications
notification.variants[].content.variants[].values[].datasources.displayText For PersistentVisualAlert notifications, this object contains the text to be displayed for the notification. Object Yes, for PersistentVisualAlert notifications
notification.variants[].content.variants[].values[].datasources.displayText.title For PersistentVisualAlert notifications, this is the title to be displayed for the notification. Maximum length is 25 characters. String Yes, for PersistentVisualAlert notifications
notification.variants[].content.variants[].values[].datasources.displayText.body For PersistentVisualAlert notifications, this is the body text to be displayed for the notification. Maximum length is 60 characters. String Yes, for PersistentVisualAlert notifications
notification.dismissalTime For PersistentVisualAlert notifications, this is the date and time of the expiry for the notification, in ISO 8601 format. Represents the time when the card expires and is removed from the display screen. String No
notification.referenceId For PersistentVisualAlert notifications, this is the reference ID of the newly created notification. The referenceId is a UUID and is unique for each notification in a unit. Use it when you need to delete or update a notification that was previously delivered. String No

Response header

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

Response body examples

All recipient processed successfully.
{
  "type": "ALL_SUCCESS",
  "message": "All message published successfully.",
  "successResults": [
    {
      "id": "amzn1.alexa.unit.did.<unitId1>",
      "referenceId": "0176a8dd-1f79-4933-a3a4-8e76fc43fd7a"
    },
    {
      "id": "amzn1.alexa.unit.did.<unitId2>",
      "referenceId": "475dc098-2319-11ec-9621-0242ac130002"
    }
  ],
  "errors": [
  ]
}

Failed to publish for some recipient.
{
  "type": "PARTIAL_SUCCESS",
  "message": "1 of 3 failed to publish.",
  "successResults": [
    {
      "id": "amzn1.alexa.unit.did.<unitId1>",
      "referenceId": "0176a8dd-1f79-4933-a3a4-8e76fc43fd7a"
    },
    {
      "id": "amzn1.alexa.unit.did.<unitId2>",
      "referenceId": "475dc098-2319-11ec-9621-0242ac130002"
    }
  ],
  "errors": [
     {
        "id":  "amzn1.alexa.unit.did.<unitId3>",
        "status": 400,
        "errorCode": "Bad Request",
        "errorDescription": "Request or recipient id is malformed."
     }
  ]
}

All message failed to publish. Reason for failure could be different for each recipient.
{
  "type": "ALL_FAILED",
  "message": "All messages failed to publish.",
  "successResults": [
       ],
  "errors": [
     {
        "id": "amzn1.alexa.unit.did.<unitId2>",
        "status": 403,
        "errorCode": "Forbidden",
        "errorDescription": "Request is forbidden."
     },
     {
        "id": "amzn1.alexa.unit.did.<unitId2>",
        "status": 400,
        "errorCode": "Bad Request",
        "errorDescription": "Request or recipient id is malformed."
     },
     {
        "id": "amzn1.alexa.unit.did.<unitId3>",
        "status": 400,
        "errorCode": "Bad Request",
        "errorDescription": "Unit already has active PersistentVisualAlert."
     }
  ]
}

Response Elements

If the action is successful, the service sends back an HTTP 202 response. The following data is returned in JSON format by the service.

Field Description Type
type Short description. String
message Detailed description of the result. String
successResults List of successfully processed units. Array
successResults[].id Successfully processed unit id. String
successResults[].referenceId Unique identifier for the unit. If a problem occurs, Amazon can use this value to troubleshoot the problem. String
errors List of unsuccessful unit ids. Array
errors[].id Unsuccessfully processed unit id. String
errors[].status Error status. Integer
errors[].errorCode Short error code. String
errors[].errorDescription Detailed description of the error for a unit. String

Error Response examples

If the action failed as whole, the service sends back an HTTP response other than 202. The following data is returned in JSON format by the service.

{
    "type": "Unauthorized",
    "message": "HTTP 401 Unauthorized"
}

Error Response element

Field Description Type
type Short description. String
message Detailed description of the result. String

HTTP response codes

Status Code Name Description
202 Accepted The request is accepted. Status of individual recipient is either inside successfulResults or errors.
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.