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 available for devices with screens. A persistent visual alert is a notification that displays on the screen until it expires or the guest or resident dismisses it. Persistent visual alerts require the premium multimodal add-on subscription. For details, see Premium Multimodal.

API endpoint

In the request header, set Host to one of the following, depending on the region of your organization:

Country Endpoint

CA, US

https://api.amazonalexa.com

DE, ES, FR, IT, UK

https://api.eu.amazonalexa.com

JP

https://api.fe.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

Delete all notifications

POST /v3/notifications/delete

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 Senior Living Core

US

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

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

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.

Copied to clipboard.

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

Copied to clipboard.

{
  "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 (requires the premium multimodal add-on).

Request body parameters

Field Description Type Required

recipients

The recipient of the notification.

Array

Yes

recipients[].type

Recipient type.
Accepted values: Unit or Endpoint. All recipients for a given request must have the same type.

Enum

Yes

recipients[].id

The endpoint or unit ID.

  • For a unit, the format is amzn1.alexa.unit.did.{identifier}.
  • For an endpoint, the format is amzn1.alexa.endpoint.{identifier}

String

Yes

notification

The notification object.

Object

Yes

notification.referenceId

The reference ID of the newly created persistent visual alert. The referenceId is a UUID and is unique for each notification in a unit. Use it when to update a notification that was previously delivered. Applies when the notification type is PersistentVisualAlert. When not provided, defaults to a generated ID value.

String

No

notification.variants[].type

Notification delivery type.
Accepted values: DeviceNotification, Announcement, or PersistentVisualAlert.

For details about the differences, see Notification types.

Enum

Yes

notification.variants[].content

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

Object

Yes

notification.variants[].content.variants[]

The locale-specific notification content to deliver to the unit.

Array of objects

Yes

notification.variants[].content.variants[].type

Type of notification. Accepted values

  • SpokenText – Send a DeviceNotification or Announcement. The notification represents localized text input.
  • V0Template – Send a PersistentVisualAlert delivery type. The notification represents an Alexa Presentation Language (APL) document that displays content on a device with a screen.

For both types, you provide the notification content within the values array.

Enum

Yes

notification.variants[].content.variants[].values[]

Content values array. Each element in the array represents localized version of the notification.

Array of objects

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. Applies when the notification type is DeviceNotification or Announcement.

String

Yes for DeviceNotification or Announcement

notification.variants[].content.variants[].values[].document

Object that defines the APL document to display. Applies when the notification type is PersistentVisualAlert.

Object

Yes, for PersistentVisualAlert notifications

notification.variants[].content.variants[].values[].document.type

Type of APL document to display. Set to Link.

String

Yes, for PersistentVisualAlert notifications

notification.variants[].content.variants[].values[].document.src

Set to one of the four supported APL templates to display:

  • Option list – doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/optionListTemplate
  • 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

Yes, for PersistentVisualAlert notifications

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

Contains the data for the specified src document. The specific fields depend on the template you set for the document.src property. See the following:

Applies when the notification type is PersistentVisualAlert.

Object

Yes, for PersistentVisualAlert notifications

notification.variants[].deliveryPreferences

Object that contains options for how Alexa should deliver the notification. Applies when the notification type is PersistentVisualAlert.

Object

No

notification.variants[].deliveryPreferences.indictor.sound

Specifies the sound to play when the notification arrives on the device.
Accepted values: SILENT, CHIME. When set to CHIME, the notification plays a chime one time when the notification arrives. Defaults to SILENT

Enumeration

No

notification.variants[].deliveryPreferences.interruption.level

Specifies how the notification interrupts any existing experience on the device. Accepted values

  • HIGH – The notification renders in the foreground and therefore interrupts the current device experience. For example, if the user is interacting with a skill, the notification interrupts the skill.
  • LOW – The notification renders in the background and replaces the home screen after the user completes their current experience. For example, if the user is interacting with a skill, the notification doens't interrupt the skill. Instead, it renders after the skill session ends.

Defaults to LOW.

Enumeration

No

notification.variants[].scheduling

An object that determines how to schedule the notification arrival and dismissal times. When not provided, Alexa delivers the notification immediately. Applies when the notification type is PersistentVisualAlert.

Provide either the scheduling property or the dismissalTime property, but not both.

Object

No

notification.variants[].scheduling.activationWindow.start

The date and time when you want the notification to arrive, in ISO 8601 format.

String

No

notification.variants[].scheduling.activationWindow.end

The date and time when you want the notification to expire, in ISO 8601 format. The notification remains on the device until this time, unless the guest or resident dismisses the notification manually.

String

No

notification.variants[].dismissalTime

The date and time of the expiry for the notification, in ISO 8601 format. The notification remains on the device until this time, unless the guest or resident dismisses the notification manually. Applies when the notification type is PersistentVisualAlert.

Provide either the scheduling property or the dismissalTime property, but not both.

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

The following example shows a response when the notification was sent to all recipients 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": [
  ]
}

The following example shows a response when the notification failed to send to some of the recipients.

{
  "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."
     }
  ]
}

The following example shows a response when the notification failed to send to all the recipients. The 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 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

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 Senior Living Core

US

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

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

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. Valid values: PersistentVisualAlert and 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 of the specified notification type 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 of the specified notification types 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.

Delete all notifications

Call POST /v3/notifications/delete to delete all notifications that are associated with the specified units.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

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

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

US

Request format

The following example shows how to delete device notifications.

POST /v3/notifications/delete
Host: api.amazonalexa.com
Content-type: application/json
Authorization: Bearer {LWA Token}

Request body examples

{
  "recipients" : [
      {
          "type": "Unit",
          "id": "amzn1.alexa.unit.did.{unitId1}"
      },
      {
          "type": "Unit",
          "id": "amzn1.alexa.unit.did.{unitId2}"
      }
   ],
  "notificationTypes" : ["PersistentVisualAlert"]  
}

Request body parameters

Parameter Description Type Required

recipients

List of IDs of units or endpoints for which to delete notifications. Minimum size: 1. Maximum size: 100.

Array

Yes

recipients[*].type

Recipient type.
Accepted values: Unit or Endpoint. All recipients for a given request must have the same type.

Enum

Yes

recipients[*].id

The endpoint or unit ID.

  • For a unit, the format is amzn1.alexa.unit.did.{identifier}.
  • For an endpoint, the format is amzn1.alexa.endpoint.{identifier}

String

Yes

notificationTypes

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

Array

Yes

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.

Error response examples

If the action fails as whole, the service sends back an HTTP response other than 202.

For example, when authorization fails with a 401 response code, the following data is returned in JSON format.

{
    "type": "Unauthorized",
    "message": "The access token is missing, expired, or invalid.",
    "errors": []
}

The following example shows the body of a 400 response when a specified unit ID is invalid.

{
   "type": "Bad Request",
   "message": "Invalid payload format, please check documentation.",
   "errors": [{
        "id": "amzn1.alexa.unit.did.{unitId1}",
        "status": 400,
        "errorCode": "Bad Request",
        "errorDescription": "Invalid UnitId."
   }]
}

The following example shows the body of a 400 response when you're not authorized to operate on one or more unit IDs.

{
   "type": "Bad Request",
   "message": "Invalid payload format, please check documentation.",
   "errors": [{
        "id": "amzn1.alexa.unit.did.{unitId1}",
        "status": 403,
        "errorCode": "Forbidden",
        "errorDescription": "User not authorized"
   },{
        "id": "amzn1.alexa.unit.did.{unitId2}",
        "status": 403,
        "errorCode": "Forbidden",
        "errorDescription": "User not authorized"
   },{
        "id": "amzn1.alexa.unit.did.{unitId3}",
        "status": 403,
        "errorCode": "Forbidden",
        "errorDescription": "User not authorized"
   }]
}

Error response element

Field Description Type

type

Short description.

String

message

Detailed description of the result.

String

errors

List of unit IDs that failed to process along with the associated error information.

String

errors[*].id

The unit ID that fails to process.

String

errors[*].status

Error status code.

Integer

errors[*].errorCode

Code that indicates the error type.

String

errors[*].errorDescription

Error description.

String

HTTP response codes

Status Code Name Description

202

Accepted

The deletion request for a list of units is accepted and being processed.

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.

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 Senior Living Core

US

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

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

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 an array of objects, where eahc object is 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 one and maximum size 100, and the only allowed field is recipients.id .
  • The value of recipients.type can be Unit or Endpoint.
  • The value of notifications.variants.type can only be PersistentVisualAlert.

A query.or is a list of minimum size one 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/textWrappingTemplate"
                      },
                      "datasources": {
                        "displayText": {
                          "primaryText": "Example notification primary text.",
                          "secondaryText": "Example notification text."
                        },
                        "background": {
                          "backgroundImageSource": "https://www.example.com/image.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 that matched the query criteria. For the possible properties of a notification, see the request body for the Send notification operation.

Array of objects

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.

Persistent visual alert templates

Persistent visual alerts require the premium multimodal add-on subscription. For details, see Premium Multimodal.

The following sections provide details about each of the available templates you can use for a persistent visual alert. Specify the template in the notification.variants[].content.variants[].values[].document.src property of the Send notifications request body. Then set the fields for the template in the notification.variants[].content.variants[].values[].datasources object.

About background images

For each of these templates, you can provide a background image with the background.backgroundImageSource property. The template scales the image uniformly up or down to completely fill the screen ("best-fill"). This means that the image might get cut off if there is a mismatch between the aspect ratio of the image and the device screen.

For best results with images, consider the following recommendations:

  • Avoid using images with text that extends to the edges of the image, as this text might be truncated due to the scaling.
  • If possible, test your images on the same device types used in your units.
  • If separate units contain different devices, consider targeting the different units with separate persistent visual alerts so that you can optimize the images for the devices. This strategy works when all the devices in a given unit have the same aspect ratio.
  • By default, the templates apply a scrim to the background image to make the text over the image easier to read. If this makes the image too dark, you can turn it off by setting the background.colorOverlay property for the template to false.

You can provide images in PNG or JPG format. The image files can't exceed 400 KB in size.

Option list

The option list template (doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/optionListTemplate) displays text, a background image, and components the user can tap to take actions you define. The template displays the content and buttons with different layouts depending on the properties you set in the request:

  • Centered text with one or more buttons – Buttons can use icons or text. You might use this variant for a daily check in with thumbs up and thumbs down buttons or a small number of multiple-choice answers. For examples, see Centered text with one or more buttons example.
  • Text displayed side-by-side with a thumbnail image – This variant displays buttons below the main text. You might use this variant to remind users of an upcoming health provider visit or property event. For an example, see Text displayed side-by-side with a thumbnail image example.
  • Menu of items with images – This variant displays each button as a thumbnail images with primary and secondary text. Users can tap on an item to trigger an action. You might use this variant to display a menu of upcoming events or food options for a meal. The template looks best when the items display in a single row, so limit the number of items to include. For an example, see Menu of items with image thumbnails example.

The option list template has the following properties within the notification.variants[].content.variants[].values[].datasources object.

Property name Description Type Required?

attributionImage.src

URL for the attribution image to display

String

No

backgroundImage.src

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

String

No

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

headerText.value

Header text displayed before all the other text fields.

String

No

hintText.value

Hint text displayed at the bottom of the screen.

String

No

optionList

An array of option objects that define the buttons to display. For the properties in this object, see Option list object.

Array

No

primaryText.value

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

String

Yes

secondaryText.value

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

String

No

thumbnailImage.src

URL for a thumbnail image to display next to the text. When provided, the template positions the text next to the image. If you set this property to an empty string, the template left-aligns the text and buttons and doesn't display an image. When not provided, the template centers the text fields.

String

No

Option list object

The optionList property accepts an array of option objects. Each object defines a button or other component that the user can tap to take an action. The template displays the buttons in different styles depending on the properties you set:

  • Icon button – Set the iconName and actions properties.
  • Text button – Set the primaryText and actions properties..
  • Menu item with a thumbnail image – Set the primaryText, secondaryText, src, and actions properties. Limit the number of items you provide to make sure that they can all fit on a single row. Three or fewer works with most devices.

The following table defines the properties you can set in an option object.

Property name Description Type Required?

actions

An array of action objects that define the actions to take when the user taps the component. A button can trigger multiple actions, such as launching a skill and dismissing the notification.

Array

No

actions[].type

The type of action to take when the user taps the button.
Accepted values:

  • SkillConnection – Launch a skill. Set connectionUri for the skill to launch and input.value to a value to pass along to the skill.
  • DismissCardAction – Dismiss the visual alert.

String

Yes

actions[].connectionUri

A URI to the skill associated with the card in the format connection://YOUR_SKILL_ID. Applies when optionList[].actions[].type is SkillConnection.

Example: connection://amzn1.ask.skill.111

String

No

actions[].input.value

The value to pass to the specified skill. Applies when optionList[].actions[].type is SkillConnection.

String

No

iconName

The name of the icon to display. You can use an icon from the Alexa Icon Library. For example, set this property to ic_like for a "thumbs up" icon or ic_dislike for a "thumbs down" icon. Ignored when src has a value.

String

No

primaryText

The text to display on the button.

  • When src contains a value, the template displays the item as a thumbnail image with the primaryText under the image.
  • When src doesn't contain a value, the template displays a rectangular button with rounded corners, unless iconName also contains a value.

String

No

secondaryText

Text to display under an image list item. Applies when primaryText and src properties contain values.

String

No

src

URI for the image to use for an item in a menu of items.

String

No

Centered text with one or more buttons example

The following example displays a quick check in notification with the thumbs up and thumbs down buttons.

Example of a check-in visual alert with thumbs up and down buttons
Example of a check-in visual alert with thumbs up and down buttons

A similar check in screen can use plain text buttons to offer a wider range of options.

Example of a check-in visual alert with multiple-choice buttons
Example of a check-in visual alert with multiple-choice buttons

Text displayed side-by-side with a thumbnail image example

The following example displays text side-by-side with an image. This layout is useful for reminders and call-to-action scenarios such as asking users to register for an event.

Example of a reminder with text and an image
Example of a reminder with text and an image

The following example displays a list of three items to provide information about available events.

Menu with image items
Menu with image items

Text wrapping

The text wrapping template has the following properties within the notification.variants[].content.variants[].values[].datasources object.

Property name Description Type Required?

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

Media

The media template has the following properties within the notification.variants[].content.variants[].values[].datasources object.

Property name Description Type Required?

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

Rating

The rating template has the following properties within the notification.variants[].content.variants[].values[].datasources object.

Property name Description Type Required?

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

Was this page helpful?

Last updated: May 09, 2024