Notifications REST API Reference

CA, US

https://api.amazonalexa.com

DE, ES, FR, IT, UK

https://api.eu.amazonalexa.com

JP

https://api.fe.amazonalexa.com

Send notifications

POST /v3/notifications

Delete notification by unit ID

DELETE /v3/notifications?recipients.id={unitid}&recipients.type={type}&notification.variants.type={variantType}

Delete all notifications

POST /v3/notifications/delete

Query persistent visual alerts

POST /v3/notifications/query

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

recipients

List of recipients of the notification.
Maximum number of items in the list: 100.

Array of objects

Yes

recipients[].type

Type of recipient.
Valid value: Unit.

String

Yes

recipients[].id

Identifies the unit.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

Yes

notification

Describes the notification.

Object

Yes

notification.variants

List of notification variants.

Array of objects

Yes

notification.variants[].type

Notification delivery type. For details about the types, see Notification types.
Valid values: DeviceNotification, Announcement, or PersistentVisualAlert.

String

Yes

notification.variants[].content

Content for the notification. The specific fields for this object depend on the type of notification.

Content object

Yes

notification.dismissalTime

Expiration date and time of the notification. Valid for notification type of PersistentVisualAlert only.
The notification remains on the device until this time, unless the guest or resident dismisses the notification manually.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

No

notification.referenceId

Reference ID of the newly created notification.
Valid for notification type of PersistentVisualAlert only.
The referenceId is unique for each notification in a unit. Include to update an already-delivered persistent visual alert.

String

No

type

Short description of the result.

String

message

Detailed description of the result.

String

successResults

List of successful notification results.

Array of objects

successResults[].id

Identifies the unit notified.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

successResults[].referenceId

Unique reference identifier for the unit and notification. 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's a one-to-one relationship between the referenceId and a notification.

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

String

errors

(Optional) List of error results.

Array

errors[].id

Identifies the unit where the notiification failed.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

errors[].status

HTTP response code for the failed request item.

Integer

errors[].errorCode

Short error code.

String

errors[].errorDescription

Human-readable error message. The error message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the error description.

String

paginationContext

Indicates whether there are more results to return.

Object

paginationContext.nextToken

Included when the response is truncated.
Use this value in a subsequent request. If no more results, nextToken is null.

String

202 Accepted

Response body contains list of success and error results.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

unitid

Query

Identifies the unit.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

Yes

recipientType

Query

Type of recipient.
Valid value: Unit.

String

Yes

variantType

Query

Notification delivery type.
Valid values: PersistentVisualAlert, DeviceNotification.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

202 Accepted

All notifications deleted from specified unit.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

US

US, UK, FR, CA, IT, DE, JP

US, UK, FR, CA, IT, DE, JP

US

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

recipients

List of recipients of the notification.
Maximum number of items in the list: 100.

Array of objects

Yes

recipients[].type

Type of recipient.
Valid value: Unit.

String

Yes

recipients[].id

Identifies the unit from which to delete notifications.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

Yes

notificationTypes

Type of notification to delete.
Maximum size: 1.
Valid values: PersistentVisualAlert, DeviceNotification.

Array of strings

Yes

type

Short description of the result.

String

message

Detailed description of the result.

String

errors

(Optional) List of error results.

Array

errors[].id

Identifies the unit where the notiification failed.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

errors[].status

HTTP response code for the failed request item.

Integer

errors[].errorCode

Short error code.

String

errors[].errorDescription

Human-readable error message. The error message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the error description.

String

202 Accepted

Deletion of all notifications accepted and processing.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

query

Filtering conditions. You can filter on recipent ID, recipient type, or reference ID.
Include one of the and or or properties.

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.

Array of objects

Yes

query.and

List of conditions to apply with a logical AND operation.
You can include the match property or another list of or filtering conditions that include the match property. These conditions are JSON-flattened with dot operator.
Example: {"and": [{"DSN": "DSN1234"}, {"UnitId": "Unit1234"}]}

A query.and must meet to the following criteria:

• Maximum size for and: 1–3 items.
• Valid match conditions for and:
  recipients.type set to Unit,
  notifications.variants.type set to PersistentVisualAlert.
• Maximum size for and.or: 1–100 items.
• Valid match conditions for and.or:
  recipients.id set to unit ID.

Array of objects

No

query.or

List of conditions to apply with a logical OR operation.
You can include the match property. These conditions are JSON-flattened with dot operator.
Example: {"or": [{"DSN": "DSN1234"}, {"DSN": "DSN5678"}]}

A query.or must meet to the following criteria:

• Maximum size for and.or: 1–100 items.
• Valid match condition: notification.reference.id

Array of objects

No

paginationContext

Pagination information. Include if iterating over a paginated response. If omitted, the first page of results are returned.

Object

No

paginationContext.maxResults

Maximum number of results to return in the response. Valid values: 1–100. Default: 10.

Integer

No

paginationContext.nextToken

Identifies the next set of data to return from a previous response. Include if iterating over a paginated response. Set to null otherwise.

String

No

successResults

List of successful notification results.

Array of objects

successResults[].recipients[].type

Type of recipient.
Valid value: Unit.

String

successResults[].recipients[].id

Identifies the unit.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

successResults[].notification

Describes the notification.

Object

successResults[].notification.variants

List of notification variants.

Array of objects

successResults[].notification.variants[].type

Notification delivery type.
Valid value: PersistentVisualAlert.

String

successResults[].notification.variants[].content

Content for the persistent visual alert.

Content object

successResults[].notification.dismissalTime

Expiration date and time of the notification.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

successResults[].referenceId

Reference ID of the notification.
This value is either a custom ID or a UUID generated by the Send notifications operation.

String

paginationContext

Indicates whether there are more results to return.

Object

paginationContext.nextToken

Included when the response is truncated.
Use this value in a subsequent request. If no more results, nextToken is null.

String

200 OK

Response body contains list of matched results.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

attribution.attributionImageSource

URL for the attribution image to display. Provide either attributionImageSource or attributionText, but not both.

String

No

attribution.attributionText

Attribution text displayed under the other text fields. Provide either attributionText or attributionImageSource, but not both.

String

No

background.backgroundImageSource

URL for the background image. When choosing images, see the recommendations in About background images.

String

No

background.colorOverlay

When true, the template applies a scrim to the background image to make it easier to read the text displayed over the image.

Boolean

No, defaults to true when not set.

displayText.headerText

Header text displayed before all the other text fields.

String

No

displayText.hintText

Hint text displayed at the bottom of the screen.

String

No

displayText.primaryText

Primary text to display. This text displays in a larger font than the rest of the text.

String

Yes

displayText.secondaryText

Secondary text displayed under the primary text in a smaller font.

String

No

displayText.tertiaryText

Tertiary text displayed next to the secondary text.

String

No

attribution.attributionImageSource

URL for the attribution image to display. Provide either attributionImageSource or attributionText, but not both.

String

No

attribution.attributionText

Attribution text displayed under the other text fields. Provide either attributionText or attributionImageSource, but not both.

String

No

background.backgroundImageSource

URL for the background image. When choosing images, see the recommendations in About background images.

String

No

background.colorOverlay

When true, the template applies a scrim to the background image to make it easier to read the text displayed over the image.

Boolean

No, defaults to true when not set.

displayText.headerText

Header text displayed before all the other text fields.

String

No

displayText.hintText

Hint text displayed at the bottom of the screen.

String

No

displayText.primaryText

Primary text to display. This text displays in a larger font than the rest of the text.

String

Yes

displayText.secondaryText

Secondary text displayed under the primary text in a smaller font.

String

No

displayText.tertiaryText

Tertiary text displayed next to the secondary text.

String

No

thumbnail.thumbnailImageSource

URL for the image thumbnail to display next to the text fields.

String

No

background.backgroundImageSource

URL for the background image. When choosing images, see the recommendations in About background images.

String

No

background.colorOverlay

When true, the template applies a scrim to the background image to make it easier to read the text displayed over the image.

Boolean

No, defaults to true when not set.

displayText.headerText

Header text displayed before all the other text fields.

String

No

displayText.hintText

Hint text displayed at the bottom of the screen.

String

No

displayText.primaryText

Primary text to display. This text displays in a larger font than the rest of the text.

String

Yes

displayText.ratingNumber

Number of stars for the rating. The rating number can be between one and five, and can include half stars, such as 3.5.

Number between one and five

Yes

displayText.ratingText

Brief text to give context to the star rating. Must be fewer than eight characters.

String

Yes

thumbnail.thumbnailImageSource

URL for the image thumbnail to display.

String

No

variants

Locale-specific notification content.

Array of objects

Yes

variants[].type

Type of content.
Valid values:

• SpokenText – Localized text input. Valid for DeviceNotification and Announcement delivery types.
• V0Template – Alexa Presentation Language (APL) document that displays content on a device with a screen. Valid for PersistentVisualAlert delivery type.

String

Yes

variants[].values

Notification content. Include for all notification types.
Each element in the array represents a localized version of the notification.

Array of objects

Yes

variants[].values[].locale

Locale in which to render the spoken text, in BCP-47 format. The locale must include both the language and country or region, for example: en-US.

String

Yes

variants[].values[].text

Spoken text in plain text format. Include when the notification type is DeviceNotification or Announcement.
Maximum length: 1024 characters or 2048 bytes.

String

No

variants[].values[].document

Defines the APL document to display. Include when the notification type is PersistentVisualAlert.

Object

No

variants[].values[].document.type

Type of APL document to display. Include when the notification type is PersistentVisualAlert.
Valid value: Link.

String

No

variants[].values[].document.src

APL template to display. Include when the notification type is PersistentVisualAlert.
Valid values:

• Text wrapping – doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/textWrappingTemplate
• Media thumbnail – doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/mediaThumbnailTemplate
• Rating – doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/ratingTemplate

String

No

variants[].values[].datasources

Data for the specified src document. Include when the notification type is PersistentVisualAlert.
The specific data depends on the template that you set for the document.src property. For details, see the following references:

• Text wrapping
• Media template
• Rating template

Object

No

type

Type of error that occurred.
For specific error types, see the HTTP status code table for each operation.

String

message

Human-readable error message. The error message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.

String