Proactive Suggestion REST API Reference

Note: Sign in to the developer console to build or publish your skill.

Note: This API is only available to registered Alexa Smart Properties partners. For more details, see Get Started with Alexa Smart Properties APIs.

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.

Note: When an Alexa-enabled device is in 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	`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). For details, see Manage API Access.

Operations

The Proactive Suggestion API includes the following operations.

Description	HTTP method and path
Create campaign	`POST /v1/proactive/campaigns`
Delete campaign	`DELETE /v1/proactive/campaigns/{campaignId}`
Get campaign	`GET /v1/proactive/campaigns/{campaignId}`
List campaigns	`GET /v1/proactive/campaigns?maxResults={maxResults}&nextToken={nextToken}`
Query campaigns	`POST /v1/proactive/campaigns/query`

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

Copied to clipboard.

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
`access token`	Header	Access token for the customer. Set to an LWA token.	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
`suggestion`	Information that Alexa can proactively deliver to users.	Object	Yes
`suggestion.variants[]`	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
`results[].suggestion.variants[].placement`	Indicates where to render the content.	`Placement` object	Yes
`suggestion.variants[].content`	Presentation data to render.	`Content` object	Yes
`targeting`	Defines the recipients of the campaign.	`Target` object	Yes
`scheduling`	Defines the schedule to activate the campaign. Default: Start time is the current time and end time is 24 hours after the current time.	`Scheduling` object	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
`campaignId`	Identifies the campaign. Use this ID when you delete the campaign or get the campaign.	String

HTTP status codes

Status	Description
`202 Accepted`	Campaign successfully created.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	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.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Delete campaign

Delete an active campaign.

Important: After you delete an active campaign, the campaign remains on the device until the device refreshes home content, about every two hours.

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

Copied to clipboard.

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
`campaignId`	Path	Identifies the campaign to delete.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	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
`202 Accepted`	Campaign deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	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.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	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

Copied to clipboard.

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
`campaignId`	Path	Identifies the campaign.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	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
`campaignId`	Identifies the campaign.	String
`suggestion`	Information that Alexa can proactively deliver to users.	Object
`suggestion.variants[]`	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
`results[].suggestion.variants[].placement`	Indicates where to render the content.	`Placement` object
`suggestion.variants[].content`	Presentation data to render.	`Content` object
`targeting`	Defines the recipients of the campaign.	`Target` object
`scheduling`	Defines the schedule to activate the campaign. Default: Start time is the current time and end time is 24 hours after the current time.	`Scheduling` object
`validationStatus`	Latest status for the campaign.	Object
`validationStatus.value`	Validation status of the campaign. Valid values: `IN_PROGRESS`, `APPROVED`, `REJECTED`.	String
`validationStatus.reason`	Explanation, if applicable, for the validation status value.	String

HTTP response codes

Status	Description
`200 OK`	Response body contains the specified campaign details.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	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.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	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

Copied to clipboard.

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
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–10. Default: 10.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response.	String	No
`access token`	Header	Access token for the customer. Set to an LWA token.	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
`results[]`	List of campaigns you created, along with a validation status for each campaign.	Array of objects
`results[].campaignId`	Identifies the campaign.	String
`results[].suggestion`	Information that Alexa can proactively deliver to users.	Object
`results[].suggestion.variants[]`	List of suggestions to present to users. The list must contain at least one variant.	Array of objects
`results[].suggestion.variants[].placement`	Indicates where to render the content.	`Placement` object
`results[].suggestion.variants[].content`	Presentation data to render.	`Content` object
`results[].targeting`	Defines the recipients of the campaign.	`Target` object
`results[].scheduling`	Defines the schedule to activate the campaign. Default: 24 hours after the current time.	`Scheduling` object
`results[].validationStatus`	Latest status for the campaign.	Object
`results[].validationStatus.value`	Validation status of 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. Included if iterating over a paginated response. If omitted, all results were already returned.	Object
`paginationContext.nextToken`	Identifies the next set of campaigns to return. Use in the next call to List campaigns.	String

HTTP response codes

Status	Description
`200 OK`	Response body contains the specified campaign details.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	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.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	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

Copied to clipboard.

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
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The following query returns active campaigns in units 101 or 102.

Copied to clipboard.

{
    "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
`query`	Filtering conditions for suggestions. Include one of the `and` or `or` properties. The query must adhere to the following rules: The query must match the structure shown in the request body examples. The query can 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 1–100 items. The only allowed field is `targeting.values.id`. The value of `targeting.type` must be `UNITS`.	Object	Yes
`query.and`	List of filtering conditions to apply by using a logical `AND` operation. You can include another list of `and` or `or` filtering conditions. These conditions are JSON-flattened with dot operator. Example: `{"and": [{"DSN": "DSN1234"}, {"UnitId": "Unit1234"}]}`	Array of strings	No
`query.or`	List of filtering conditions to apply by using a logical `OR` operation. You can include another list of `and` or `or` filtering conditions. These conditions are JSON-flattened with dot operator. Example: `{"or": [{"DSN": "DSN1234"}, {"DSN": "DSN5678"}]}`	Array of strings	No
`paginationContext`	Pagination information. Include if iterating over a paginated response. If omitted, the response includes the first page of results.	Object	No
`paginationContext.maxResults`	Maximum number of results to return in the response. Valid values: 1–100. Default: 10.	Integer	No
`paginationContext.nextToken`	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
`results[]`	List of campaigns you created, along with a validation status for each campaign.	Array of objects
`results[].campaignId`	Identifies the campaign.	String
`results[].suggestion`	Information that Alexa can proactively deliver to users.	Object
`results[].suggestion.variants[]`	List of suggestions to present to users. The list must contain at least one variant.	Array of objects
`results[].suggestion.variants[].placement`	Indicates where to render the content.	`Placement` object
`results[].suggestion.variants[].content`	Presentation data to render.	`Content` object
`results[].targeting`	Defines the recipients of the campaign.	`Target` object
`results[].scheduling`	Defines the schedule to activate the campaign. Default: 24 hours after the current time.	`Scheduling` object
`results[].validationStatus`	Latest status for the campaign.	Object
`results[].validationStatus.value`	Validation status of 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. Included if iterating over a paginated response. If omitted, all results were already returned.	Object
`paginationContext.nextToken`	Identifies the next set of campaigns to return. Use in the next call to List campaigns.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the specified campaign details.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	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.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	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:

Text wrapping
Media
Rating
For your day
On this day
Photo card

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