Proactive Suggestion API


For Alexa Smart Properties property operators, the home screen on Alexa multimodal devices provides an opportunity for branding, upselling products and services (such as happy hours and spa services), and informing guests about events, updates, and skills.

As a solution integrator, you can use the Alexa Proactive Suggestion REST API to enable property managers to provide visual content to Alexa as suggestions. From those suggestions, Alexa chooses content items and displays them to customers on their devices' home screens. To create the visual experience for your suggestions, you use Alexa Presentation Language (APL).

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 Proactive Suggestion API includes the following operations.

Description HTTP method and path

Create a campaign

POST /v1/proactive/campaigns

List campaigns

GET /v1/proactive/campaigns?maxResults={maxResults}&nextToken={nextToken}

Query campaigns

POST /v1/proactive/campaigns/query

Get a campaign

GET /v1/proactive/campaigns/{campaignId}

Delete a campaign

DELETE /v1/proactive/campaigns/{campaignId}

Create a campaign

Creates a campaign that renders the content as a suggestion to targeted recipients.

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 /v1/proactive/campaigns HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body format

The request body contains a campaign entity that encapsulates the suggestion along with recipients and scheduling specifics for the information. The following example shows a campaign entity.

{
    "suggestion": {
        "variants": [{
            "placement": {
                "channel": "HOME"
            },
            "content": {
                "values": [{
                    "locale": "en-US",
                    "document": {},
                    "datasources": {}
                }]
            }
        }]
    },
    "targeting": {
       (polymorphic object of type units)
    },
    "scheduling": {
        "activationWindow": {
            "start": "2021-01-01T10:00:00.00Z",
            "end": "2021-01-31T10:00:00.00Z"
        }
    }
}

Request body example

The following example shows a request body for a campaign. This example displays the en-US content on English (US) devices and the pt-BR content on Portuguese (Brazil) devices. The device always displays only one campaign per locale.

{
   "suggestion": {
      "variants": [
         {
            "placement": {
               "channel": "HOME"
            },
            "content": {
               "values": [
                  {
                    "locale": "en-US",
                    "document": {
                       "type": "Link",
                       "src": "<placeholderLinkToDocument>"
                    },
                    "datasources": {
                       "displayText": {
                          "primaryText": "Example notification title.",
                          "secondaryText": "Example notification text.",
                          "action": {
                              "type": "SkillConnection",
                              "uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345",
                              "input": {}
                          }                          
                       },
                       "background": {
                          "backgroundImageSource": "https://www.example.com/image.jpg"
                       }                       
                    }
                  },
                  {
                    "locale": "pt-BR",
                    "document": {
                       "type": "Link",
                       "src": "<placeholderLinkToDocument>"
                    },
                    "datasources": {
                       "displayText": {
                          "primaryText": "Exemplo de título de notificação.",
                          "secondaryText": "Texto de notificação de exemplo.",
                          "action": {
                              "type": "SkillConnection",
                              "uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345",
                              "input": {}
                          }                             
                       },
                       "background": {
                          "backgroundImageSource": "https://www.example.com/image.jpg"
                       }                         
                    }
                  }
                ]
            }
        }]
   },
   "targeting": {
      "type": "UNITS",
      "values": [
        {
           "id": "amzn1.alexa.unit.did.unitId"
        }
      ]
   },
   "scheduling": {
      "activationWindow": {
         "start": "2021-01-01T10:00:00.00Z",
         "end": "2021-01-31T10:00:00.00Z"
      }
   }
}

Request body parameters

Field Description Type Required

suggestion

A piece of information that Alexa can proactively deliver to users.

Object

Yes

suggestion.variants[]

A list of suggestion variants to present to users. The list must contain at least one variant. Note that you can provide at most one variant per placement channel.

Array

Yes

suggestion.variants[].placement

The place to render the content.

Object

Yes

suggestion.variants[].placement.channel

The name of the channel. Currently the only supported value is "HOME", which refers to the home screen on Alexa multimodal devices. You can provide at most one variant per placement channel in a single request.

String

Yes

suggestion.variants[].content.values[]

Array of objects that contains localized presentation data specific to the default content type. You must provide at least one localized presentation data element. You can provide multiple objects in this array to cover different locales. However, don't define more than one object per locale. For a device in given locale, the device displays the first object that matches that locale.

Array

Yes

suggestion.variants[].content.values[].locale

The locale in which the content is rendered, in BCP-47 format. The locale must include both the language and country or region, for example: en-US.

String

Yes

suggestion.variants[].content.values[].document

A link to the APL document to use for rendering. For details, see Use a linked document with RenderDocument. Not all APL features are supported.

String

Yes

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

The APL document type. Must be Link.

String

Yes

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

The APL document link. There are multiple supported templates to choose from. Set this property to the specified document link for the template to use.

  • Text wrappingdoc://alexa/apl/documents/home/cards/textWrapping
  • Media thumbnaildoc://alexa/apl/documents/home/cards/media
  • Ratingdoc://alexa/apl/documents/home/cards/rating
  • For your daydoc://alexa/apl/documents/home/cards/suggestedActions
  • On this daydoc://alexa/apl/documents/home/cards/primePhoto
  • Photo carddoc://alexa/apl/documents/home/cards/selectedPhoto

String

Yes

suggestion.variants[].content.values[].datasources

Object that can contain other objects that bind data to the APL document. The specific fields you provide in the datasources object depends on the template you set for the document.src property. See the following:

Map of data source objects

Yes

targeting

Polymorphic object that defines the recipients of the campaign. Target type: units.

Object

Yes

scheduling

The scheduling information for the campaign. If this field isn't present, the default start time is the current time and the end time is 24 hours after the current time.

Object

No

scheduling.activationWindow

A time window object specifying the time in which a campaign is active.

Object

Yes if you include scheduling

scheduling.activationWindow.start

The start of the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. The default value is the current time.

String

No

scheduling.activationWindow.end

The end of the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. Must be later than or equal to the start time. The default value is 24 hours after the current time.

String

No

Units target

The units that the campaign targets.

{
   "type": "UNITS",
   "values": [
      {
         "id": "amzn1.alexa.unit.did.unitId"
      }
   ]
}
Field Description Type Required

type

The type of targeting criteria that should be applied. Accepted value: UNITS.

String

Yes

values[]

A list of objects that contain rooms' unit IDs in the form of amzn1.alexa.unit.did.{id}. This list can contain at most 100 unit IDs.

Array

Yes

values[].id

A room's unit ID in the form of amzn1.alexa.unit.did.{id}.

String

Yes

Success response header

HTTP/1.1 202 Accepted
Host: {host value used in the request}
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type Required

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Yes

Response body format

{
    "campaignId": "{exampleId}"
}

Response body parameters

Field Description Type

campaignId

Campaign ID for the campaign. You use this ID when you delete the campaign or get the campaign.

String

HTTP response codes

Status Code Name Description

201

Created

The campaign was successfully created.

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 access token is valid, but the user doesn't have the needed LWA scope permissions.

429

Too Many Requests

Request has been throttled.

500

Internal Server Error

The request couldn't be handled because of an internal service error.

503

Service Unavailable

Service is temporarily unavailable.

List campaigns

Lists the campaigns you've created.

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

GET /v1/proactive/campaigns?maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body format

None.

Request path parameters

Field Description Type Required

maxResults

Maximum number of results to display. The value of this parameter must be between 1 and 10. The default value is 10.

Integer

No

nextToken

Continuation token returned in the response object of the previous response to list campaigns.

String

No

Success response header

Host: {host value used in the request}
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type Required

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Yes

Response body format

{
   "results": [
      {
         "campaignId": "campaignId",
         "suggestion": {
            "variants": [{
               "placement": {
                  "channel": "HOME"
               },
               "content": {
                  "values": [{
                     "locale": "en-US",
                     "document": {},
                     "datasources": {}
                  }]
               }
            }]          
         },
         "targeting": {
            (polymorphic object of type units)
         },
         "scheduling": {
            "activationWindow": {
               "start": "2021-01-01T10:00:00.00Z",
               "end": "2021-01-31T10:00:00.00Z"
            }
         },
         "validationStatus": {
            "value": "string enum",   // IN_PROGRESS, APPROVED, or REJECTED
            "reason": "Explanation"
         }
     },
     {
        ... (another campaign and status) ...
     }
   ],
   "paginationContext": {
      "nextToken": "token from previous call"
   }
}

Response body parameters

Field Description Type

results[]

The list of campaigns you created, along with a validation status for each.

Array

results[].campaign

The details you submitted when you created the campaign. For the fields, see the request body format for creating a campaign.

Object

results[].validationStatus

The latest validation status for the campaign.

Object

results[].validationStatus.value

Enum that describes the latest validation status for the campaign. Valid values: IN_PROGRESS, APPROVED, REJECTED.

String

results[].validationStatus.reason

Explanation, if applicable, for the validation status value.

String

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 list campaigns.

String

HTTP response codes

Status Code Name Description

202

Request Accepted

The request was accepted.

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 access token is valid, but the user doesn't have the needed LWA scope permissions.

429

Too Many Requests

Request has been throttled.

500

Internal Server Error

The request couldn't be handled because of an internal service error.

503

Service Unavailable

Service is temporarily unavailable.

Query campaigns

Queries the campaigns for a list of 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

POST /v1/proactive/campaigns/query HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body format

The following query returns active suggestions using one or more units.

{
    "query": {
        "and": [
            {
                "or": [
                    {
                        "match": {
                            "targeting.values.id": "U1"
                        }
                    },
                    {
                        "match": {
                            "targeting.values.id": "U2"
                        }
                    }
                ]
            },
            {
                "match": {
                    "targeting.type": "UNITS"
                }
            }
        ]
    },
    "paginationContext": {
        "maxResults": 10,
        "nextToken": "paginationTokenString"
    }
 }

Request body parameters

Field Description Type Required

query

Object that provides filtering conditions to get suggestions. This object has only one allowed field, which can be either AND or OR. Each of these fields is a list type. These fields are usually followed by a filtering condition on a certain attribute of suggestions. These fields can also 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 the structure shown in the request body examples.
  • The query can only have one and operation.
  • The only allowed condition is match.
  • query.and is a list of two items.
  • query.and.or is a list of minimum size 1 and maximum size 100. The only allowed field is targeting.values.id.
  • The value of targeting.type can only be UNITS.

Query object

Yes

paginationContext

Object that contains pagination information.

Object

No

paginationContext.maxResults

Maximum number of suggestions to return in one request. The value of this parameter must be between 1 and 100. The default value is 10.

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

and

Conditions to apply using a logical AND operation.

Example: {"and": [{"DSN": "DSN1234"}, {"UnitId": "Unit1234"}]}

Array

No

or

Conditions to apply using a logical OR operation.

Example: {"or": [{"DSN": "DSN1234"}, {"DSN": "DSN5678"}]}

Array

No

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
Content-Type: application/json
X-Amzn-RequestId: sample-request-id-value
Field Description Type Required

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Yes

Response body example

{
    "paginationContext": {
        "nextToken": "paginationTokenString"
    },
    "results": [
        {
            "campaignId": "sample-id",
            "validationStatus": {
                "value": "IN_PROGRESS",
                "reason": "Explanation"
            },
            "suggestion": {
                "variants": [
                    {
                        "placement": {
                            "channel": "HOME"
                        },
                        "content": {
                            "values": [
                                {
                                    "locale": "en-US",
                                    "document": {
                                        "type": "Link",
                                        "src": "<placeholderLinkToDocument>"
                                    },
                                    "datasources": {
                                        "displayText": {
                                            "primaryText": "Light and warm patio breakfast",
                                            "secondaryText": "Breakfast is served until 11:30 am!"
                                        }
                                    }
                                },
                                {
                                    "locale": "pt-BR",
                                    "document": {
                                        "type": "Link",
                                        "src": "<placeholderLinkToDocument>"
                                    },
                                    "datasources": {
                                        "displayText": {
                                            "primaryText": "Café da manhã leve e quente no pátio",
                                            "secondaryText": "O café da manhã é servido até as 11h30!"
                                        }
                                    },
                                    "background": {
                                        "backgroundImageSource": "https://url-of-image.jpg"
                                    }
                                }
                            ]
                        }
                    }
                ]
            },
            "targeting": {
                "type": "UNITS",
                "values": [
                    {
                        "id": "amzn1.alexa.unit.did.unitId"
                    }
                ]
            },
            "scheduling": {
                "activationWindow": {
                    "start": "2021-01-01T10:00:00.00Z",
                    "end": "2021-01-31T10:00:00.00Z"
                }
            }
        }
    ]
 }

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 campaigns. If this field is null, all evaluation results were already returned. If this field isn't null, there are more evaluation results in the next page.

String

results[*]

The list of campaigns you created for the unit, along with a validation status for each campaign.

Array

results[*].campaignId

Campaign ID.

String

results[*].validationStatus

The latest validation status for the campaign.

Object

results[*].validationStatus.value

Enum that describes the latest validation status for the campaign. Valid values: IN_PROGRESS, APPROVED, REJECTED.

String

results[*].validationStatus.reason

Explanation, if applicable, for the validation status value.

String

results[*].suggestion

The message to deliver to users.

Object

results[*].suggestion.variants[*]

A list of suggestion variants to present to users. The list must contain at least one variant.

Array

results[*].suggestion.variants[*].placement

The place where the content can be rendered.

Object

results[*].suggestion.variants[*].placement.channel

The name of the channel. Currently the only supported value is "HOME", which refers to the home screen on Alexa multimodal devices.

String

results[*].suggestion.variants[*].content.values[*]

Object that contains localized presentation data specific to the default content type. At least one localized presentation data element must be present.

Array

results[*].suggestion.variants[*].content.values[*].locale

The locale in which the content is rendered, in BCP-47 format. The locale must include both the language and country or region, for example: en-US.

String

results[*].suggestion.variants[*].content.values[*].document

A link to the APL document to use for rendering. For details, see Use a linked document with RenderDocument. Not all APL features are supported.

Object

results[*].suggestion.variants[*].content.values[*].document.type

The APL document type. Must be Link.

String

results[*].suggestion.variants[*].content.values[*].document.src

The APL document link.

String

results[*].suggestion.variants[*].content.values[*].datasources

Object that can contain other objects that bind data to the APL document. The specific fields in this object depend on the template specified in the document.src property. See the following:

Object

results[*].targeting

Polymorphic object that defines the recipients of the campaign. One of three types of targets: units, users, or skill subscribers.

Object

results[*].targeting.type

The type of targeting criteria that should be applied.

String

results[*].targeting.values[*]

A list of objects that contain rooms' unit IDs in the form amzn1.alexa.unit.did.{id}.

Array

results[*].targeting.values[*].id

A room's unit ID in the form amzn1.alexa.unit.did.{id}.

String

results[*].scheduling

The scheduling information for the campaign.

Object

results[*].scheduling.activationWindow

A time window object specifying the time in which a campaign is active.

Object

scheduling.activationWindow.start

The start of the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

scheduling.activationWindow.end

The end of the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

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.

Get a campaign

Retrieves an active campaign that you created. This operation doesn't return expired campaigns.

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

GET /v1/proactive/campaigns/{campaignId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body format

None.

Request path parameters

Field Description Type Required

campaignId

The ID of the active campaign to retrieve. This value is returned when you create a campaign.

String

Yes

Success response header

Host: {host value used in the request}
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type Required

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Yes

Response body format

{
   "campaignId": "campaignId",
   "suggestion": {
      "variants": [{
         "placement": {
            "channel": "HOME"
         },
         "content": {
            "values": [{
               "locale": "en-US",
               "document": {},
               "datasources": {}
            }]
         }
      }]  
   },
   "targeting": {
      (polymorphic object of type units)
   },
   "scheduling": {
      "activationWindow": {
         "start": "2021-01-01T10:00:00.00Z",
         "end": "2021-01-31T10:00:00.00Z"
      }
   },
   "validationStatus": {
      "value": "string enum",   // IN_PROGRESS, APPROVED, or REJECTED
      "reason": "Explanation"
   }
}

Response body parameters

Field Description Type

Campaign information

The details you submitted when you created the campaign. For the fields, see the request body format for creating a campaign.

Object

ValidationStatus

The status of the campaign validation.

Object

validationStatus

The latest validation status for the campaign.

Object

validationStatus.value

The latest validation status for the campaign. Valid values: IN_PROGRESS, APPROVED, REJECTED.

String

validationStatus.reason

Explanation, if applicable, for the validation status value.

String

HTTP response codes

Status Code Name Description

200

Successful

The request was processed successfully.

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 access token is valid, but the user doesn't have the needed LWA scope permissions.

404

Not Found

The provided campaignId didn't match an active campaign. Make sure the campaignId is correct and that it doesn't refer to an expired campaign.

429

Too Many Requests

Request has been throttled.

500

Internal Server Error

The request couldn't be handled because of an internal service error.

503

Service Unavailable

Service is temporarily unavailable.

Delete a campaign

Deletes a campaign.

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 /v1/proactive/campaigns/{campaignId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required

campaignId

The ID of the campaign to delete. This value is returned when you create a campaign.

String

Yes

Request body

None.

Success response header

HTTP/1.1 202 OK
Host: {host value used in the request}
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type Required

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Yes

Response body

None.

HTTP response codes

Status Code Name Description

202

Accepted

The delete request for the specified campaign has been accepted. The campaign will be deleted, but there's no guarantee that the suggestion wasn't already delivered.

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 access token is valid, but the user doesn't have the needed LWA scope permissions.

404

Not Found

The campaign to delete isn't found.

429

Too Many Requests

Request has been throttled.

500

Internal Server Error

The request couldn't be handled because of an internal service error.

Campaign templates

The following sections provide details about each of the available templates you can use for a proactive campaign. Specify the template in the suggestion.variants[].content.values[].document.src property of the Create a campaign request body. Then set the fields for the template in the suggestion.variants[].content.values[].datasources property.

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 proactive campaigns 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.

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

Text wrapping

The Text wrapping template (doc://alexa/apl/documents/home/cards/textWrapping) displays text over a background image. The template can also include a button to launch a skill.

This template has the following properties within the suggestion.variants[].content.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. Maximum character count: 35.

String

No

background.backgroundImageSource

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

String

No

displayText.headerText

Header text displayed before all the other text fields. Maximum character count: 80.

String

No

displayText.hintText

Hint text displayed at the bottom of the screen. Maximum character count: 60.

String

No

displayText.primaryText

Primary text to display. This text displays in a larger font than the rest of the text. Maximum character count: 60.

String

Yes

displayText.secondaryText

Secondary text displayed under the primary text in a smaller font. Maximum character count: 80.

String

No

displayText.tertiaryText

Tertiary text displayed next to the secondary text. Maximum character count: 25.

String

No

displayText.playbackEnabled

When true, display a "Play" button before the primary text. When the user taps the button, the specified action occurs.

Boolean

No

displayText.callToActionButtonText

When set, display an action button with the provided label below the text. When the user taps the button, the specified action occurs. Maximum character count: 35.

String

No

displayText.action

An object that defines the action to take when the user taps either the playback button or the action button.

Object

Yes

displayText.action.type

The type of action.
Accepted values: SkillConnection.

String

Yes

displayText.action.uri

A URI to the skill associated with the card in the format connection://AMAZON.ColdLaunch/1?provider=YOUR_SKILL_ID.

Example: connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345.

String

Yes

Media

The Media template (doc://alexa/apl/documents/home/cards/media) displays a large thumbnail image alongside text.

This template has the following properties within the suggestion.variants[].content.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. Maximum character count: 35.

String

No

background.backgroundImageSource

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

String

No

displayText.headerText

Header text displayed before all the other text fields. Maximum character count: 40.

String

No

displayText.hintText

Hint text displayed at the bottom of the screen. Maximum character count: 35.

String

No

displayText.primaryText

Primary text to display. This text displays in a larger font than the rest of the text. Maximum character count: 40.

String

Yes

displayText.secondaryText

Secondary text displayed under the primary text in a smaller font. Maximum character count: 25.

String

No

displayText.tertiaryText

Tertiary text displayed next to the secondary text. Maximum character count: 25.

String

No

thumbnail.thumbnailImageSource

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

String

No

Rating

The Rating template (doc://alexa/apl/documents/home/cards/rating) displays text along with a star rating.

This template has the following properties within the suggestion.variants[].content.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

displayText.headerText

Header text displayed before all the other text fields. Maximum character count: 60.

String

No

displayText.hintText

Hint text displayed at the bottom of the screen. Maximum character count: 35.

String

No

displayText.primaryText

Primary text to display. This text displays in a larger font than the rest of the text. Maximum character count: 60.

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. Maximum character count: 8.

String

Yes

thumbnail.thumbnailImageSource

URL for the image thumbnail to display.

String

No

For your day

The For your day template (doc://alexa/apl/documents/home/cards/suggestedActions) displays up to three items with hint text and thumbnail images. You can define an action to run when the user taps the items.

The number of items the template displays depends on the size of the device. For example, an Echo Show 15 displays all three, and an Echo Show 8 displays the first two. A small device such as an Echo Show 5 displays a single item.

The template has the following properties within the suggestion.variants[].content.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

displayText.headerText

Header text displayed before all the other text fields. Maximum character count: 60.

String

No

displayText.listItems

Array of up to three list item objects to display.

Array of objects

No

displayText.listItems[].hintText

Text to display for the item. Maximum character count: 80.

String

No

displayText.listItems[].thumbnailSource

URL for the image thumbnail to display before the hintText.

String

No

displayText.action

An object that defines the action to take when the user taps any of the list items. You can define a single action, which is used by all of the list items.

Object

Yes

displayText.action.type

The type of action.
Accepted values: SkillConnection.

String

Yes

displayText.action.uri

A URI to the skill associated with the card in the format connection://AMAZON.ColdLaunch/1?provider=YOUR_SKILL_ID.

Example: connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345.

String

Yes

displayText.action.input

Data to pass to the skill. This functionality isn't supported, so set this property to an empty object {}.

Object

Yes

On this day

The On this day template (doc://alexa/apl/documents/home/cards/primePhoto) displays a full screen photo with brief text.

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

Property name Description Type Required?

background.backgroundImageSource

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

String

No

displayText.headerText

Header text displayed before all the other text fields. Maximum character count: 60.

String

No

displayText.hintText

Hint text displayed at the bottom of the screen. Maximum character count: 35.

String

No

displayText.primaryText

Primary text to display that displays after the header. Maximum character count: 60.

String

Yes

displayText.action

An object that defines the action to take when the user taps anywhere on the screen.

Object

Yes

displayText.action.type

The type of action.
Accepted values: SkillConnection.

String

Yes

displayText.action.uri

A URI to the skill associated with the card in the format connection://AMAZON.ColdLaunch/1?provider=YOUR_SKILL_ID.

Example: connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345.

String

Yes

displayText.action.input

Data to pass to the skill. This functionality isn't supported, so set this property to an empty object {}.

Object

Yes

Photo card

The Photo card template (doc://alexa/apl/documents/home/cards/selectedPhoto) displays a full screen photo with brief primary and secondary text.

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

Property name Description Type Required?

background.backgroundImageSource

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

String

No

displayText.hintText

Hint text displayed at the bottom of the screen. Maximum character count: 35.

String

No

displayText.primaryText

Primary text to display that displays in a slightly larger font. Maximum character count: 60.

String

Yes

displayText.secondaryText

Primary text to display that displays below the primary text. Maximum character count: 80.

String

Yes

displayText.action

An object that defines the action to take when the user taps anywhere on the screen.

Object

Yes

displayText.action.type

The type of action.
Accepted values: SkillConnection.

String

Yes

displayText.action.uri

A URI to the skill associated with the card in the format connection://AMAZON.ColdLaunch/1?provider=YOUR_SKILL_ID.

Example: connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345.

String

Yes

displayText.action.input

Data to pass to the skill. This functionality isn't supported, so set this property to an empty object {}.

Object

Yes


Was this page helpful?

Last updated: Oct 02, 2024