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.

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.

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}"
      },
      {
        "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/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-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.
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 a 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 BCP-47 format. The locale must include both the language and country or region, for example: en-US.

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 three supported APL templates to display:

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

String

No

notification.referenceId

For PersistentVisualAlert notifications, this is the reference ID of the newly created notification. The referenceId is an UUID and is unique for each notification in a unit. This ID is required 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

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 for which to delete notifications. Minimum size: 1. Maximum size: 100.

Array

Yes

recipients[*].type

Type of recipient for which to delete notifications. Valid value: Unit.

Enum

Yes

recipients[*].id

ID of the unit for which to delete notifications. Must be in the format "amzn1.alexa.unit.did.{id}".

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 each object is a filtering condition on a certain attribute, and can encompass another list of nested and/or filtering conditions. To flatten the fields you can query, use 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 only be Unit.
  • 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

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"). As a result, if there is a mismatch between the aspect ratio of the image and the device screen, the image might get cut off.

For best results with images, consider the following recommendations:

  • Avoid 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 the scrim 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.

Text wrapping template data source

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 template data source

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 template data source

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: Aug 07, 2024