Proactive Suggestion REST API Reference
Use the Proactive Suggestion REST API to display interactive content on Alexa-enabled devices with a screen in Alexa Smart Properties (ASP). With this API, property operators can provide visual content to guests, such as branding, offering products and services, such as happy hours and spa services, and informing guests about events, updates, and skills.
You provide visual content to Alexa as suggestions. From the 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).
For more details, see Send proactive suggestions.
DoNotDisturb
mode, proactive suggestion campaigns only appear when the user has interacted with Alexa recently. After a few minutes of no interaction with Alexa, the device returns to showing the clock.API endpoint
Based on the country of your organization, set the Host
parameter in the request header to one of the following API endpoints.
Country | Endpoint |
---|---|
CA, US |
|
DE, ES, FR, IT, UK |
|
JP |
|
Authentication
Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Manage API Access.
Operations
The Proactive Suggestion API includes the following operations.
Description | HTTP method and path |
---|---|
| |
| |
| |
| |
|
Create campaign
Create 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
To create a campaign, you make a POST
request to the /v1/proactive/campaigns
resource.
Request path and header example
POST /v1/proactive/campaigns HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
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.
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.
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Information that Alexa can proactively deliver to users. |
Object |
Yes |
|
List of suggestion variants to present to users. The list must contain at least one variant. You can provide at most one variant per placement channel. |
Array of objects |
Yes |
|
Indicates where to render the content. |
|
Yes |
|
Presentation data to render. |
|
Yes |
|
Defines the recipients of the campaign. |
|
Yes |
|
Defines the schedule to activate the campaign. |
|
No |
Response
A successful response returns HTTP 202 Accepted
, along with campaign ID.
On error, the response returns the appropriate HTTP status code and includes a response body with an Error object. The response also includes X-Amzn-RequestId
, a unique string identifier that Amazon uses to troubleshoot when a problem occurs.
Response body example
{
"campaignId": "campaign.id.1"
}
Response body properties
Property | Description | Type |
---|---|---|
|
Identifies the campaign. |
String |
HTTP status codes
Status | Description |
---|---|
|
Campaign successfully created. |
|
Indicates that one or more properties in the request body aren't valid. |
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Delete campaign
Delete an active 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
To delete a campaign, you make a DELETE
request to the /v1/proactive/campaigns
resource.
Request path and header example
DELETE /v1/proactive/campaigns/{campaignId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the campaign to delete. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 202 Accepted
.
On error, the response returns the appropriate HTTP status code and includes a response body with an Error object. The response also includes X-Amzn-RequestId
, a unique string identifier that Amazon uses to troubleshoot when a problem occurs.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Campaign deleted successfully. |
|
Indicates that one or more properties in the request body aren't valid. |
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get 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
To get a campaign, you make a GET
request to the /v1/proactive/campaigns
resource.
Request path and header example
GET /v1/proactive/campaigns/{campaignId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the campaign. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the specified campaign.
On error, the response returns the appropriate HTTP status code and includes a response body with an Error object. The response also includes X-Amzn-RequestId
, a unique string identifier that Amazon uses to troubleshoot when a problem occurs.
Response body example
Response body properties
Property | Description | Type |
---|---|---|
|
Identifies the campaign. |
String |
|
Information that Alexa can proactively deliver to users. |
Object |
|
List of suggestion variants to present to users. The list must contain at least one variant. You can provide at most one variant per placement channel. |
Array of objects |
|
Indicates where to render the content. |
|
|
Presentation data to render. |
|
|
Defines the recipients of the campaign. |
|
|
Defines the schedule to activate the campaign. |
|
|
Latest status for the campaign. |
Object |
|
Validation status of the campaign. |
String |
|
Explanation, if applicable, for the validation status value. |
String |
HTTP response codes
Status | Description |
---|---|
|
Response body contains the specified campaign details. |
|
Indicates that one or more properties in the request body aren't valid. |
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List campaigns
Lists the campaigns that you 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
To list campaigns, you make a GET
request to the /v1/proactive/campaigns
resource.
Request path and header example
GET /v1/proactive/campaigns?maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
Query |
Token from the previous response. |
String |
No |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with a list of campaigns.
On error, the response returns the appropriate HTTP status code and includes a response body with an Error object. The response also includes X-Amzn-RequestId
, a unique string identifier that Amazon uses to troubleshoot when a problem occurs.
Response body format
Response body properties
Property | Description | Type |
---|---|---|
|
List of campaigns you created, along with a validation status for each campaign. |
Array of objects |
|
Identifies the campaign. |
String |
|
Information that Alexa can proactively deliver to users. |
Object |
|
List of suggestions to present to users. The list must contain at least one variant. |
Array of objects |
|
Indicates where to render the content. |
|
|
Presentation data to render. |
|
|
Defines the recipients of the campaign. |
|
|
Defines the schedule to activate the campaign. |
|
|
Latest status for the campaign. |
Object |
|
Validation status of the campaign. |
String |
|
Explanation, if applicable, for the validation status value. |
String |
|
Object containing pagination information. Included if iterating over a paginated response. If omitted, all results were already returned. |
Object |
|
Identifies the next set of campaigns to return. Use in the next call to List campaigns. |
String |
HTTP response codes
Status | Description |
---|---|
|
Response body contains the specified campaign details. |
|
Indicates that one or more properties in the request body aren't valid. |
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Query campaigns
Query 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
To query campaigns, you make a GET
request to the /v1/proactive/campaigns/query
resource.
Request path and header example
POST /v1/proactive/campaigns/query HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The following query returns active campaigns in units 101 or 102.
{
"query": {
"and": [{
"or": [{
"match": {
"targeting.values.id": "101"
}
},
{
"match": {
"targeting.values.id": "102"
}
}
]
},
{
"match": {
"targeting.type": "UNITS"
}
}
]
},
"paginationContext": {
"maxResults": 10,
"nextToken": "someToken.1"
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Filtering conditions for suggestions.
|
Object |
Yes |
|
List of filtering conditions to apply by using a logical |
Array of strings |
No |
|
List of filtering conditions to apply by using a logical |
Array of strings |
No |
|
Pagination information. Include if iterating over a paginated response. If omitted, the response includes the first page of results. |
Object |
No |
|
Maximum number of results to return in the response. |
Integer |
No |
|
Identifies the set of campaigns to return. Include if iterating over a paginated response. Set to null otherwise. |
String |
No |
Response
A successful response returns HTTP 200 OK
, along with a list of filtered campaigns,
On error, the response returns the appropriate HTTP status code and includes a response body with an Error object. The response also includes X-Amzn-RequestId
, a unique string identifier that Amazon uses to troubleshoot when a problem occurs.
Response body example
Response body properties
Property | Description | Type |
---|---|---|
|
List of campaigns you created, along with a validation status for each campaign. |
Array of objects |
|
Identifies the campaign. |
String |
|
Information that Alexa can proactively deliver to users. |
Object |
|
List of suggestions to present to users. The list must contain at least one variant. |
Array of objects |
|
Indicates where to render the content. |
|
|
Presentation data to render. |
|
|
Defines the recipients of the campaign. |
|
|
Defines the schedule to activate the campaign. |
|
|
Latest status for the campaign. |
Object |
|
Validation status of the campaign. |
String |
|
Explanation, if applicable, for the validation status value. |
String |
|
Object containing pagination information. Included if iterating over a paginated response. If omitted, all results were already returned. |
Object |
|
Identifies the next set of campaigns to return. Use in the next call to List campaigns. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the specified campaign details. |
|
Indicates that one or more properties in the request body aren't valid. |
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Campaign templates
To add a card to the home screen of Alexa-enabled devices with a screen, you create a campaign for a list of units. Specify the template name in the suggestion.variants[].content.values[].document.src
property of the Create campaign request body. Then set the properties for the template in the suggestion.variants[].content.values[].datasources
property.
You can choose from the following campaign templates:
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 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 displays text over a background image. The template can also include a button to launch a skill.
Template name: doc://alexa/apl/documents/home/cards/textWrapping
To use this template, set the following properties within the suggestion.variants[].content.values[].datasources
object.
Property name | Description | Type | Required |
---|---|---|---|
|
URL for the attribution image to display. Provide either |
String |
No |
|
Attribution text displayed under the other text fields. Provide either |
String |
No |
|
URL for the background image. When choosing images, see the recommendations in About background images. |
String |
No |
|
Header text displayed before all the other text fields. |
String |
No |
|
Hint text displayed at the bottom of the screen. |
String |
No |
|
Primary text to display. This text displays in a larger font than the rest of the text. |
String |
Yes |
|
Secondary text displayed under the primary text in a smaller font. |
String |
No |
|
Tertiary text displayed next to the secondary text. |
String |
No |
|
When |
Boolean |
No |
|
When set, display an action button with the provided label below the text. When the user taps the button, the specified |
String |
No |
|
Defines the action to take when the user taps the playback button or the action button. |
Object |
Yes |
|
Type of action. |
String |
Yes |
|
URI to the skill associated with the card . |
String |
Yes |
Media
The Media template displays a large thumbnail image alongside text.
Template name: doc://alexa/apl/documents/home/cards/media
To use this template, set the following properties within the suggestion.variants[].content.values[].datasources
object.
Property name | Description | Type | Required |
---|---|---|---|
|
URL for the attribution image to display. Provide either |
String |
No |
|
Attribution text displayed under the other text fields. Provide either |
String |
No |
|
URL for the background image. When choosing images, see the recommendations in About background images. |
String |
No |
|
Header text displayed before all the other text fields. |
String |
No |
|
Hint text displayed at the bottom of the screen. |
String |
No |
|
Primary text to display. This text displays in a larger font than the rest of the text. |
String |
Yes |
|
Secondary text displayed under the primary text in a smaller font. |
String |
No |
|
Tertiary text displayed next to the secondary text. |
String |
No |
|
URL for the image thumbnail to display next to the text fields. |
String |
No |
Rating
The Rating template displays text along with a star rating.
Template name: doc://alexa/apl/documents/home/cards/rating
To use this template, set the following properties within the suggestion.variants[].content.values[].datasources
object.
Property name | Description | Type | Required |
---|---|---|---|
|
URL for the background image. When choosing images, see the recommendations in About background images. |
String |
No |
|
Header text displayed before all the other text fields. |
String |
No |
|
Hint text displayed at the bottom of the screen. |
String |
No |
|
Primary text to display. This text displays in a larger font than the rest of the text. |
String |
Yes |
|
Number of stars for the rating. The rating number can be between one and five, and can include half stars, such as |
Number between one and five |
Yes |
|
Brief text to give context to the star rating. |
String |
Yes |
|
URL for the image thumbnail to display. |
String |
No |
For your day
The For your day template 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 items and an Echo Show 8 displays the first two items. A small device, such as an Echo Show 5, displays a single item.
Template name: doc://alexa/apl/documents/home/cards/suggestedActions
To use this template, set the following properties within the suggestion.variants[].content.values[].datasources
object.
Property name | Description | Type | Required |
---|---|---|---|
|
URL for the background image. When choosing images, see the recommendations in About background images. |
String |
No |
|
Header text displayed before all the other text fields. |
String |
No |
|
Array of up to three list item objects to display. |
Array of objects |
No |
|
Text to display for the item. |
String |
No |
|
URL for the image thumbnail to display before the |
String |
No |
|
Defines the action to take when the user taps on a list item on the screen. |
Object |
Yes |
|
Type of action. |
String |
Yes |
|
URI to the skill associated with the card . |
String |
Yes |
|
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 displays a full screen photo with brief text.
Template name: doc://alexa/apl/documents/home/cards/primePhoto
To use this template, set the following properties within the suggestion.variants[].content.values[].datasources
object.
Property name | Description | Type | Required |
---|---|---|---|
|
URL for the image to display. When choosing images, see the recommendations in About background images. |
String |
No |
|
Header text displayed before all the other text fields. |
String |
No |
|
Hint text displayed at the bottom of the screen. |
String |
No |
|
Primary text to display that displays after the header. |
String |
Yes |
|
Defines the action to take when the user taps anywhere on the screen. |
Object |
Yes |
|
Type of action. |
String |
Yes |
|
URI to the skill associated with the card . |
String |
Yes |
|
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 displays a full screen photo with brief primary and secondary text.
Template name: doc://alexa/apl/documents/home/cards/selectedPhoto
To use this template, set the following properties within the suggestion.variants[].content.values[].datasources
object.
Property name | Description | Type | Required |
---|---|---|---|
|
URL for the image to display. When choosing images, see the recommendations in About background images. |
String |
No |
|
Hint text displayed at the bottom of the screen. |
String |
No |
|
Primary text to display that displays in a slightly larger font. |
String |
Yes |
|
Primary text to display that displays below the primary text. |
String |
Yes |
|
Defines the action to take when the user taps anywhere on the screen. |
Object |
Yes |
|
Type of action. |
String |
Yes |
|
URI to the skill associated with the card . |
String |
Yes |
|
Data to pass to the skill. This functionality isn't supported, so set this property to an empty object |
Object |
Yes |
Object definitions
The Proactive Suggestion API defines the following objects.
Content object
The Content object encapsulates the presentation data to render for the campaign.
Property | Description | Type | Required |
---|---|---|---|
|
List of 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 for each locale However, don't define more than one object per locale. For a device in given the locale, the device displays the first object that matches that locale. |
List of objects |
Yes |
|
Locale in which to render the content. The locale must include both the language and country or region, for example: |
String |
Yes |
|
Link to the APL document to render. |
Object |
Yes |
|
APL document type. |
String |
Yes |
|
APL document link.
|
String |
Yes |
|
Use to bind data to the APL document. The specific fields you provide depends on the template you set for the |
Map of |
Yes |
|
Text to render in the title field of the document. |
String |
No |
|
Text to render in the body field of the document. |
String |
No |
Error object
The Error
object defines the error type and message included in the response when an error occurs.
The following example shows the response body with the error type and message.
{
"type": "BAD_REQUEST",
"message": "The request is malformed or is missing any required parameters."
}
Property | Description | Type |
---|---|---|
|
Type of error that occurred. |
String |
|
Human-readable error message. The error message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String |
Placement object
The Placement
object defines where to render the suggestion on the screen.
Property | Description | Type | Required |
---|---|---|---|
|
Name of the channel. |
String |
Yes |
Scheduling object
The Scheduling
object defines the schedule to activate the campaign.
Property | Description | Type | Required |
---|---|---|---|
|
Specifies the time in which a campaign is active. If not included in a request, Alexa uses default values. |
Object |
No |
|
Start time of the activation window. |
String |
No |
|
End of the time of the activation window. |
String |
No |
Target object
The Target
object defines either the units that the campaign targets.
Field | Description | Type | Required |
---|---|---|---|
|
Type of targeting criteria to apply. |
String |
Yes |
|
List of rooms targeted in the campaign. This list can contain at most 100 unit IDs. Note: The unit IDs must be for rooms, not properties or room types.
|
Array of strings |
Yes |
|
Identifies the unit. |
String |
units.items
) still works. However, for new implementations, use the current format of the API shown previously.Related topics
Last updated: Nov 26, 2024