Use the Notifications API to Send Persistent Visual Alerts

Use the Notifications API in Alexa Smart Properties (ASP) to send persistent visual alerts to units or endpoints in your property. A persistent visual alert is a notification that displays content on a device with a screen, and remains visible until a defined expiration time or the guest or resident dismisses the alert. With the API, you can use advanced alert features that aren't available in the console, such as additional templates, chime settings, and scheduling.

Send a persistent visual alert

Use the send notifications operation of the API to send the visual alert to a list of units or endpoints. You provide the recipients and alert content in the body of the request:

  • Set the alert type (notification.variants[].type) to PersistentVisualAlert
  • Specify a template for the visual in the notification.variants[].content.variants[].values[].document.src property. You can choose from four templates. For an overview of the templates, see Templates.
  • Set values for the content fields in the notification.variants[].content.variants[].values[].datasources object properties. The specific fields depend on the selected template.
  • Optionally specify whether to play a chime on arrival in the notification.variants[].deliveryPreferences object. By default, the alert doesn't play a chime.
  • Optionally define a schedule for when the notification should arrive in the notification.variants[].scheduling object. If not provided, the notification delivers within five seconds after you send it.

The following example shows a visual alert that uses the Text wrapping template to remind the guest to take a walk. The notification is scheduled to deliver at a specific time and plays a chime when it arrives on the device.

Copied to clipboard.

POST /v3/notifications HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
{
  "recipients": [
    {
      "type": "Unit",
      "id": "amzn1.alexa.unit.did.1"
    }
  ],
  "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": "Exercise Reminder",
                      "secondaryText": "Time to take a walk!"
                    },
                    "background": {
                      "backgroundImageSource": "https://example.com/images/background-blue.png",
                      "colorOverlay": "true"
                    }
                  }
                }
              ]
            }
          ]
        },
        "deliveryPreferences": {
          "indicator": {
            "sound": {
              "type": "CHIME"
            }
          }
        },
        "scheduling": {
          "activationWindow": {
            "start": "2024-04-30T21:50:11Z",
            "end": "2024-04-30T22:50:00Z"
          }
        }
      }
    ]
  }
}

For details about the send notification operation, see Send notifications.

Templates

The send notifications operation requires you to specify a template and the data to display within that template.

The template is a link to an Alexa Presentation Language (APL) document. You can specify one of the documents shown in the following table.

Name Description

Option list

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

Text wrapping

doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/textWrappingTemplate

Displays basic text over a background. You can include a header, primary, secondary, and tertiary text.

Media thumbnail

doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/mediaThumbnailTemplate

Displays text side-by-side with a thumbnail image, over an image background.

Rating

doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/ratingTemplate

Displays text and an image over an image background, along with a star rating.

For details about the templates and the specific properties you can set for each one, see Persistent visual alert templates.

Was this page helpful?

Last updated: frontmatter-missing