Proactive Suggestion API

The Proactive Suggestion REST API enables you to display glanceable, interactive content on the home page of Alexa devices with screens.

With this API, you provide visual content to Alexa as suggestions. To create the visual experience for your suggestions, you use Alexa Presentation Language (APL).

Endpoint

The endpoint for the Proactive Suggestion API is https://api.amazonalexa.com.

Operations

The Proactive Suggestion API includes the following operations.

Description HTTP method and path

Create a campaign

POST /v1/proactive/campaigns

Delete a campaign

DELETE /v1/proactive/campaigns/{campaignId}

Create a campaign

Call POST /v1/proactive/campaigns to create a campaign that renders the content as a suggestion to targeted customers.

Request format

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

Request body format

The POST /v1/proactive/campaigns request body contains a campaign entity, as shown in the following example.

{
    "suggestion": {
        "variants": [{
            "placement": {
                "channel": "HOME"
            },
            "content": {
                "values": [{
                    "locale": "en-US",
                    "document": {},
                    "datasources": {}
                }]
            }
        }]
    },
    "targeting": {
        "units": {
            "items": [
                "amzn1.alexa.unit.did.{unitId}"
            ]
        }
    },
    "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": "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!"
                            }
                        }
                    }
                ]
            }
        }]
    },
    "targeting": {
        "units": {
            "items": [
                "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

The message to be delivered to customers.

Object

Yes

suggestion.variants[]

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

Array

Yes

suggestion.variants[].placement

The place where the content can be rendered.

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.

String

Yes

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.

Object

Yes

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

The locale in which the content is rendered, in IETF BCP 47 format.

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. Currently only "doc://alexa/apl/documents/enterprise/suggestions/home/defaultTemplate" is supported.

String

Yes

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

Object that can contain other objects that can be used to bind data to the APL document.

Map of data source objects

Yes

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

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 25 characters.

String

No

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

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

No

targeting

Object that defines the recipients of the campaign.

Object

Yes

targeting.units

Object containing the units that a campaign is targeting.

Object

Yes

targeting.units.items

A list of unit IDs, one for each unit to be targeted. For details, see Create a room. Currently the list must exactly one unit ID.

Array of Strings

Yes

scheduling

The scheduling information for the campaign.

Entity

Yes

scheduling.activationWindow

A time window object specifying the time in which a campaign is active. If this field is not specified, Alexa uses default values.

Object

No

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

Success response header

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
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": "{sampleId}"
}

Response body parameters

Field Description Type Required

campaignId

Campaign ID for the campaign.

String

Yes

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.

Delete a campaign

Call DELETE /v1/proactive/campaigns/{campaignId} to delete a campaign.

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

Campaign ID for the campaign to be deleted.

String

Yes

Request body

None.

Success response header

HTTP/1.1 202 OK
Host: api.amazonalexa.com
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.

204

No Content

The specified campaign doesn't exist.

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.