Notifications API

Note: Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.

Note: This API is only available to registered Alexa Smart Properties core partners. See Get Started with Alexa Smart Properties Core APIs.

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`

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

Note: The result of sending a notification to each unit is reported individually in the response. Because the batch request can result in a combination of successful and unsuccessful actions, you should check for batch errors even when the call returns an HTTP status code of 202 (accepted) response code.

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.