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
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.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 |
---|---|---|---|
|
The recipient of the notification. |
Array |
Yes |
|
Recipient type: |
Enum |
Yes |
|
The unit ID, in the format |
String |
Yes |
|
The notification object. |
Object |
Yes |
|
Notification delivery type: |
Enum |
Yes |
|
Notification content helps developers specifying different variants of content for spoken and display purposes. |
Object |
Yes |
|
The locale-specific notification content to be delivered to the end user. |
Array |
Yes |
|
Type of content: |
Enum |
Yes |
|
Content values array. Each element in the array represents localized text input. |
Array |
Yes |
|
The locale in which the spoken text is rendered, in IETF BCP 47 format. |
String |
Yes |
|
Spoken text in plain text format. Maximum length is 1024 characters or 2048 bytes. |
String |
Yes |
|
For |
Object |
Yes, for |
|
For |
String |
Yes, for |
|
For |
String |
Yes, for |
|
For |
Object |
Yes, for |
|
For |
Object |
Yes, for |
|
For |
String |
Yes, for |
|
For |
String |
Yes, for |
|
Object that specifies different aspects of the background. |
Object |
No |
|
URL for the background image. |
String |
Yes, if you include |
|
For |
String |
No |
|
For |
String |
No |
Response header
Host
value is the same as the Host
value in the request.HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type |
---|---|---|
|
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 |
---|---|---|
|
Short description. |
String |
|
Detailed description of the result. |
String |
|
List of successfully processed units. |
Array |
|
Successfully processed unit ID. |
String |
|
Unique identifier for the unit. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
|
List of unsuccessful unit IDs. |
Array |
|
Unsuccessfully processed unit ID. |
String |
|
Error status. |
Integer |
|
Short error code. |
String |
|
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 |
---|---|---|
|
Short description. |
String |
|
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 |
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¬ification.variants.type=DeviceNotification
to delete all notifications associated with a unit.
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.DELETE /v3/notifications?recipients.id={unitid}&recipients.type=Unit¬ification.variants.type=DeviceNotification
Host: api.amazonalexa.com
Content-type: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
Unit ID, in the format |
String |
Yes |
|
Recipient type: |
String |
Yes |
|
Notification delivery type: |
String |
Yes |
Request body examples
The request has no body.
Request body parameters
The request has no body.
Response header
Host
value is the same as the Host
value in the request.HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
Content-Type: application/json
X-Amzn-RequestId: {request-id}
Response header parameters
Field | Description | Type |
---|---|---|
|
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 |
---|---|---|
|
Short description. |
String |
|
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 |
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. |