Notifications API

You can use the Alexa Notifications REST API to send notifications to your customers.

Notification types

This API can deliver notifications to up to a hundred different units in a single request. You can specify one of the following notification types:

  • Device notification – For Alexa-enabled devices without screens, the device notification is a yellow ring and a chime sound. For devices with screens, the device notification is a banner and a persistent notification indicator.
  • Announcement – For devices with and without screens, Alexa makes announcements by voice. Devices with screens also display a message on the screen.
  • Persistent visual alert – Persistent visual alerts are only for devices with screens. A persistent visual alert is a notification that's displayed on the screen until it expires or the guest or resident dismisses it.

API endpoint

The endpoint of the Notifications API is https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA).

Operations

The Notifications API includes the following operations.

Operation HTTP Method and URI

Send notifications

POST /v3/notifications

Delete notification by unit ID

DELETE /v3/notifications

Query persistent visual alerts

POST /v3/notifications/query

Send notifications

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

This operation is available in the following countries.

Healthcare Hospitality Residential Senior Living Core

US

US, UK, FR, CA, IT, DE

None

US, UK, FR, CA, IT, DE

US

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": "Example notification text."
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

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": "Example notification text."
                    }]
                }]
            }
        }]
    }
}

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": "Example notification title.",
                                "body": "Example notification text."
                            },
                            "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 parameters

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.

This operation is available in the following countries.

Healthcare Hospitality Residential Senior Living Core

US

US, UK, FR, CA, IT, DE

None

US, UK, FR, CA, IT, DE

US

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.

Query persistent visual alerts

To query the persistent visual alerts present in a list of units, call POST /v3/notifications/query.

This operation is available in the following countries.

Healthcare Hospitality Residential Senior Living Core

US

US, UK, FR, CA, IT, DE

None

US, UK, FR, CA, IT, DE

US

Request format

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

Request body format

{
    "query": {},
    "paginationContext": {
        "maxResults": 10,
        "nextToken": "paginationTokenString"
    }
 }

Request parameters

Field Description Type Required

query

Object that provides filtering conditions. This object has only one allowed field, which can be either AND or OR. Each of these fields is a list type. These fields are usually followed by a filtering condition on a certain attribute, and can encompass another list of nested AND/OR filtering conditions. Queryable fields are JSON-flattened using the "." operator.

The query must adhere to the following rules:

  • The query must match one of the general structures shown in the request body examples.
  • The query can only have one key and operation or one key or operation.
  • The only allowed condition is match.

A query.and is a list of three items and meets the following criteria:
  • A query.and.or is a list of minimum size 1 and maximum size 100, and the only allowed field is recipients.id .
  • The value of recipients.type can only be Unit.
  • The value of notifications.variants.type can only be PersistentVisualAlert.

A query.or is a list of minimum size 1 and maximum size 100, and meets the following criteria:
  • The only allowed field is notification.referenceId.

Object

Yes

paginationContext.maxResults

Maximum number of items to return in one request. Minimum value: 1. Maximum value: 100.

Integer

No

paginationContext.nextToken

Token you use to retrieve subsequent data in the previous response, if applicable. This field must either be null or a valid value returned from the server.

String

No

Query object

Field Description Type Required

or

Conditions to apply using a logical OR operation.

Example: {"or": [{"DSN": "DSN1234"}, {"DSN": "DSN5678"}]}

Array

No

and

Conditions to apply using a logical AND operation.

Example: {"and": [{"DSN": "DSN1234"}, {"UnitId": "Unit1234"}]}

Array

No

Request body example that gets active persistent visual alert notifications for one or more units

The following example gets active persistent visual alert notifications for one or more units.

{
   "query": {
      "and": [
        {
           "or": [
             {
                "match": {
                   "recipients.id": "U1"
                }
             },
             {
                "match": {
                   "recipients.id": "U2"
                }
             }
           ]
        },
        {
           "match": {
              "recipients.type": "Unit"
           }
        },
        {
           "match": {
              "notification.variants.type": "PersistentVisualAlert"
           }
        }
      ]
   },
   "paginationContext": {
      "maxResults": 10,
      "nextToken": "paginationTokenString"
   }
}

Request body example that gets active notifications using one or more reference IDs

The following example gets active notifications using one or more reference IDs.

{
   "query": {
     "or": [
       {
          "match": {
             "notification.referenceId": "R1"
          }
         },
         {
          "match": {
             "notification.referenceId": "R2"
          }
       }
     ]
   },
   "paginationContext": {
      "maxResults": 10,
      "nextToken": "paginationTokenString"
   }
}

Response header

HTTP/1.1 200 OK
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 example (success)

The following example shows a complete or partially successful response.

{
    "paginationContext": {
        "nextToken": "paginationTokenString"
    },
    "successResults": [
        {
            "recipients": [
                {
                    "type": "Unit",
                    "id": "amzn1.alexa.unit.did.{unitId1}"
                }
            ],
            "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": "Example title",
                                                    "body": "Example body"
                                                }
                                            },
                                            "background": {
                                                "backgroundImageSource": "https://s3.amazon.com/example_background_large.jpg"
                                            }
                                        }
                                    ]
                                }
                            ]
                        },
                        "dismissalTime": "2021-04-30T10:00:00.00Z"
                    }
                ],
                "referenceId": "595973fd-5b66-4970-9401-example"
            }
        }
    ]
 }

Response body example (error)

The following example shows an error response.

{
    "type": "BAD_REQUEST",
    "message": "Invalid payload format, please check documentation."
 }

Response body parameters

Field Description Type

paginationContext

Object containing pagination information. If omitted, all evaluation results were already returned.

Object

paginationContext.nextToken

Continuation token that you use in the next call to query persistent visual alerts. If this field is null, all evaluation results were already returned. If this field isn't null, there are more results in the next page.

String

results[*]

List of persistent visual alert notifications.

Array

results[*].recipients[*]

Recipient of the notification.

Array

results[*].recipients[*].type

Recipient type: Unit.

Enum

results[*].recipients[*].id

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

String

results[*].notifications[*]

Objects that contain units and active notifications.

Array

results[*].notifications[*].variants[*].type

Notification delivery type: DeviceNotification, Announcement, or PersistentVisualAlert. See Notification types.

Enum

results[*].notifications[*].variants[*].content

Object that enables you to specify different variants of notification content for spoken and display purposes.

Object

results[*].notifications[*].variants[*].content.variants[*]

The locale-specific notification content to be delivered to the end user.

Array

results[*].notifications[*].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

results[*].notifications[*].variants[*].content.variants[*].values[*]

Content values array. Each element in the array represents localized text input.

Array

results[*].notifications[*].variants[*].content.variants[*].values[*].locale

Locale in which the spoken text is rendered, in IETF BCP 47 format.

String

results[*].notifications[*].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

results[*].notifications[*].variants[*].content.variants[*].values[*].document.type

For PersistentVisualAlert notifications, this is the APL document type. Must be Link.

String

results[*].notifications[*].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

results[*].notifications[*].variants[*].content.variants[*].values[*].datasources

For PersistentVisualAlert notifications, this is the APL document data.

Object

results[*].notifications[*].variants[*].content.variants[*].values[*].datasources.displayText

For PersistentVisualAlert notifications, this object contains the text to be displayed for the notification.

Object

results[*].notifications[*].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

results[*].notifications[*].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

results[*].notifications[*].variants[*].content.variants[*].values[*].datasources.background

Object that specifies different aspects of the background.

Object

results[*].notifications[*].variants[*].content.variants[*].values[*].datasources.background.backgroundImageSource

URL for the background image.

String

results[*].notifications[*].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

results[*].notifications[*].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

HTTP response codes

Status Code Name Description

200

OK

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

Request is throttled.

500

Internal Server Error

The request couldn't be handled because of an internal service error.

503

Service Unavailable

Service is temporarily unavailable.