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).
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
In the request header, set Host
to one of the following, depending on the region of your organization:
Country | Endpoint |
---|---|
CA, US |
|
DE, ES, FR, IT, UK |
|
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
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 |
US, UK, FR, CA, IT, DE, ES |
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
{
"suggestion": {
"variants": [
{
"placement": {
"channel": "HOME"
},
"content": {
"values": [
{
"locale": "en-US",
"document": {
"type": "Link",
"src": "<placeholderLinkToDocument>"
},
"datasources": {
"displayText": {
"title": "Example notification title.",
"body": "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": {
"title": "Exemplo de título de notificação.",
"body": "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 |
---|---|---|---|
|
A piece of information that Alexa can proactively deliver to users. |
Object |
Yes |
|
A list of suggestion variants to present to users. The list must contain at least one variant. |
Array |
Yes |
|
The place where the content can be rendered. |
Object |
Yes |
|
The name of the channel. Currently the only supported value is |
String |
Yes |
|
Object that contains localized presentation data specific to the default content type. At least one localized presentation data element must be present. |
Object |
Yes |
|
The locale in which the content is rendered, in IETF BCP 47 format. |
String |
Yes |
|
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 |
|
The APL document type. Must be |
String |
Yes |
|
The APL document link. There are three supported templates. Set this property to the specified document link for the template to use.
|
String |
Yes |
|
Object that can contain other objects that bind data to the APL document. The specific fields you provide in the |
Map of data source objects |
Yes |
|
Polymorphic object that defines the recipients of the campaign. Target type: units. |
Object |
Yes |
|
The scheduling information for the campaign. If this field is not present, the default start time is the current time and the end time is 24 hours after the current time. |
Object |
No |
|
A time window object specifying the time in which a campaign is active. |
Object |
Yes if you include |
|
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 |
|
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 |
Text wrapping template data source
The text wrapping template has 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. |
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 |
Media template data source
The media template has 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 |
|
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 template data source
The rating template has the following properties within the suggestion.variants[].content.values[].datasources
object.
Property name | Description | Type | Required? |
---|---|---|---|
|
URL for the background image. |
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. Must be fewer than eight characters. |
String |
Yes |
|
URL for the image thumbnail to display. |
String |
No |
Units target
The units that the campaign targets.
{
"type": "UNITS",
"values": [
{
"id": "amzn1.alexa.unit.did.unitId"
}
]
}
Field | Description | Type | Required |
---|---|---|---|
|
The type of targeting criteria that should be applied. Accepted value: |
String |
Yes |
|
A list of objects that contain rooms' unit IDs in the form of Note: The unit IDs must be for rooms, not properties or room types.
|
Array |
Yes |
|
A room's unit ID in the form of |
String |
Yes |
units.items
) still works. However, for new implementations, use the current format of the API shown previously.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 |
---|---|---|---|
|
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 |
---|---|---|
|
Campaign ID for the campaign. You use this ID when you delete the campaign or get the campaign. |
String |
referenceId
, which is a unique identifier that Amazon generates for a request.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 |
US, UK, FR, CA, IT, DE, ES |
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 |
---|---|---|---|
|
Maximum number of results to display. The value of this parameter must be between 1 and 10. The default value is 10. |
Integer |
No |
|
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 |
---|---|---|---|
|
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 |
---|---|---|
|
The list of campaigns you created, along with a validation status for each. |
Array |
|
The details you submitted when you created the campaign. For the fields, see the request body format for creating a campaign. |
Object |
|
The latest validation status for the campaign. |
Object |
|
Enum that describes the latest validation status for the campaign. Valid values: |
String |
|
Explanation, if applicable, for the validation status value. |
String |
|
Object containing pagination information. If omitted, all evaluation results were already returned. |
Object |
|
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 |
US, UK, FR, CA, IT, DE |
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 |
---|---|---|---|
|
Object that provides filtering conditions to get suggestions. This object has only one allowed field, which can be either
|
Yes | |
|
Object that contains pagination information. |
Object |
No |
|
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 |
|
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 |
---|---|---|---|
|
Conditions to apply using a logical |
Array |
No |
|
Conditions to apply using a logical |
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 |
---|---|---|---|
|
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": {
"title": "Light and warm patio breakfast",
"body": "Breakfast is served until 11:30 am!"
}
}
},
{
"locale": "pt-BR",
"document": {
"type": "Link",
"src": "<placeholderLinkToDocument>"
},
"datasources": {
"displayText": {
"title": "Café da manhã leve e quente no pátio",
"body": "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 |
---|---|---|
|
Object containing pagination information. If omitted, all evaluation results were already returned. |
Object |
|
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 |
|
The list of campaigns you created for the unit, along with a validation status for each campaign. |
Array |
|
Campaign ID. |
String |
|
The latest validation status for the campaign. |
Object |
|
Enum that describes the latest validation status for the campaign. Valid values: |
String |
|
Explanation, if applicable, for the validation status value. |
String |
|
The message to deliver to users. |
Object |
|
A list of suggestion variants to present to users. The list must contain at least one variant. |
Array |
|
The place where the content can be rendered. |
Object |
|
The name of the channel. Currently the only supported value is |
String |
|
Object that contains localized presentation data specific to the default content type. At least one localized presentation data element must be present. |
Array |
|
The locale in which the content is rendered, in IETF BCP 47 format. |
String |
|
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 |
|
The APL document type. Must be |
String |
|
The APL document link. Currently only |
String |
|
Object that can contain other objects that can be used to bind data to the APL document. |
Object |
|
The text to be rendered in the title field of the document. This text is displayed in a large font on the home screen. Maximum length is 60 characters. |
String |
|
The text to be rendered in the body field of the document. This text is displayed in a smaller font below the title on the home screen. Maximum length is 60 characters. |
String |
|
Object that specifies different aspects of the background. |
Object |
|
URL for the background image. |
String |
|
Polymorphic object that defines the recipients of the campaign. One of three types of targets: units, users, or skill subscribers. |
Object |
|
The type of targeting criteria that should be applied. |
String |
|
A list of objects that contain rooms' unit IDs in the form |
Array |
|
A room's unit ID in the form |
String |
|
The scheduling information for the campaign. |
Object |
|
A time window object specifying the time in which a campaign is active. |
Object |
|
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 |
|
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 a campaign that you created.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
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 |
---|---|---|---|
|
The ID of the 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 |
---|---|---|---|
|
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 |
|
The status of the campaign validation. |
Object |
|
The latest validation status for the campaign. |
Object |
|
The latest validation status for the campaign. Valid values: |
String |
|
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 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. |
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 |
US, UK, FR, CA, IT, DE, ES |
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 |
---|---|---|---|
|
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 |
---|---|---|---|
|
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. |
Related topics
Related topics
Last updated: Nov 28, 2023