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!"
                            },
                            "background": {
                                "backgroundImageSource": "https://www.example.com/image.jpg"
                            }
                        }
                    }]
                }]
            },
            "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.variants[].content.variants[].values[].datasources.background

Object that specifies different aspects of the background.

Object

No

notification.variants[].content.variants[].values[].datasources.background.backgroundImageSource

URL for the background image.

String

Yes, if you include notification.variants[].content.variants[].values[].datasources.background

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 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.

For notifications of type DeviceNotification, the referenceId is a unique ID for each notification created for each unit. In other words, there is a one-to-one relationship between the referenceId and a notification.

For notifications of type PersistentVisualAlert, you provide the referenceId when you send the notification. In this case, all units have the same referenceId, forming a one-to-many relationship between referenceId and the notification.

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.

Delete notification by unit ID

Call DELETE /v3/notifications?recipients.id={unitid}&recipients.type=Unit&notification.variants.type=DeviceNotification to delete all notifications associated with a unit.

Request format

DELETE /v3/notifications?recipients.id={unitid}&recipients.type=Unit&notification.variants.type=DeviceNotification
Host: api.amazonalexa.com
Content-type: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required

recipients.id

Unit ID, in the format amzn1.alexa.unit.did.{unitId}.

String

Yes

recipients.type

Recipient type: Unit.

String

Yes

notification.variants.type

Notification delivery type: DeviceNotification.

String

Yes

Request body examples

The request has no body.

Request body parameters

The request has no body.

Response header

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
Content-Type: application/json
X-Amzn-RequestId: {request-id}

Response header parameters

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

A successful response doesn't contain a body. Upon successfully receiving a deletion request, the server returns an HTTP 202 OK status response. The server returns this response even if the specified unit doesn't have any notification of type DeviceNotification to delete.

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 deletion request for the specified unit was accepted. All DeviceNotifications for this unit are deleted.

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.