Proactive Suggestion REST API Reference

Use the Proactive Suggestion REST API to display interactive content on Alexa-enabled devices with a screen. 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).

For more details, see Add Content to the Home Screen of Alexa Devices.

API endpoint

The endpoint of the Proactive Suggestion API is https://api.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 Get an Access Token for SMAPI.

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}

Create campaign

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

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
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

LWA token.

String

Yes

Request body example

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

Copied to clipboard.

{
    "suggestion": {
        "variants": [{
            "placement": {
                "channel": "HOME"
            },
            "content": {
                "values": [{
                    "locale": "en-US",
                    "document": {
                        "type": "Link",
                        "src": "doc://alexa/apl/documents/home/cards/textWrapping"
                    },
                    "datasources": {
                        "displayText": {
                            "headerText": "YourHeaderText",
                            "primaryText": "YourPrimaryText",
                            "secondaryText": "YourSecondaryText",
                            "attributionText": "YourAttributionText",
                            "hintText": "Try \"{WakeWord}, open SkillName\"",
                            "action": {
                                "type": "SkillConnection",
                                "uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.1",
                                "input": {}
                            }
                        },
                        "background": {
                            "backgroundImageSource": "http://url-of-background-image"
                        }
                    }
                }]
            }
        }]
    },
    "targeting": {
        "type": "SKILL_SUBSCRIBERS"
    },
    "scheduling": {
        "activationWindow": {
            "start": "2021-09-20T21:25:27.179Z",
            "end": "2021-10-22T00:25:27.179Z"
        }
    }
}

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.

Array of objects

Yes

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: 24 hours after the current time.

Scheduling object

Yes

Response

A successful response returns HTTP 202 Accepted, along with the list metadata. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message. The response also includes X-Amzn-RequestId, a unique string identifier that Amazon uses to troubleshoot when a problem occurs.

Response body example

The following example shows a response.

"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.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. 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

Deletes a campaign.

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}
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

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 code and human readable message. 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.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. 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

Retrieve the specified campaign.

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}
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

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 code and human readable message.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",
    "suggestion": {
        "variants": [{
            "placement": {
                "channel": "HOME"
            },
            "content": {
                "values": [{
                    "locale": "en-US",
                    "document": {
                        "type": "Link",
                        "src": "doc://alexa/apl/documents/home/cards/textWrapping"
                    },
                    "datasources": {
                        "displayText": {
                            "headerText": "YourHeaderText",
                            "primaryText": "YourPrimaryText",
                            "secondaryText": "YourSecondaryText",
                            "attributionText": "YourAttributionText",
                            "hintText": "Try \"{WakeWord}, open SkillName\"",
                            "action": {
                                "type": "SkillConnection",
                                "uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.1",
                                "input": {}
                            }
                        },
                        "background": {
                            "backgroundImageSource": "http://url-of-background-image"
                        }
                    }
                }]
            }
        }]
    },
    "targeting": {
        "type": "SKILL_SUBSCRIBERS"
    },
    "scheduling": {
        "activationWindow": {
            "start": "2021-01-01T10:00:00.00Z",
            "end": "2021-01-31T10:00:00.00Z"
        }
    },
    "validationStatus": {
        "value": "APPROVED",
        "reason": "Explanation"
    }
}

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 suggestions to present to users. The list must contain at least one variant.

Array of objects

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: 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 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.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. 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.

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}
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.

Integer

No

nextToken

Query

Token from the previous response.
Include if iterating over a paginated response.

String

No

access token

Header

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 code and human readable message. The response also includes X-Amzn-RequestId, a unique string identifier that Amazon uses to troubleshoot when a problem occurs.

Response body example

{
    "results": [{
        "campaignId": "campaign.id.2",
        "suggestion": {
            "variants": [{
                "placement": {
                    "channel": "HOME"
                },
                "content": {
                    "values": [{
                        "locale": "en-US",
                        "document": {
                            "type": "Link",
                            "src": "doc://alexa/apl/documents/home/cards/textWrapping"
                        },
                        "datasources": {
                            "displayText": {
                                "headerText": "YourHeaderText",
                                "primaryText": "YourPrimaryText",
                                "secondaryText": "YourSecondaryText",
                                "attributionText": "YourAttributionText",
                                "hintText": "Try \"{WakeWord}, open SkillName\"",
                                "action": {
                                    "type": "SkillConnection",
                                    "uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.1",
                                    "input": {}
                                }
                            },
                            "background": {
                                "backgroundImageSource": "http://url-of-background-image"
                            }
                        }
                    }]
                }
            }]
        },
        "targeting": {
            "type": "USERS",
            "values": [{
                "id": "amzn1.ask.account.1"
            }]
        },
        "scheduling": {
            "activationWindow": {
                "start": "2021-01-01T10:00:00.00Z",
                "end": "2021-01-31T10:00:00.00Z"
            }
        },
        "validationStatus": {
            "value": "IN_PROGRESS",
            "reason": "Explanation"
        }
    }],
    "paginationContext": {
        "nextToken": "someToken.1"
    }
}

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

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. 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.

Object definitions

The Proactive Suggestion API defines the following object definitions.

Content object

The Content object encapsulates the presentation data to render for the campaign.

Property Description Type Required

values[]

List of localized presentation data specific to the default content type. At least one localized presentation data element must be present.

List of objects

Yes

values[].locale

Locale in which to render the content.
Format in IETF BCP 47 format.

String

Yes

values[].document

Link to the APL document to render.
For more details, see Use a linked document with RenderDocument.
Not all APL features are supported.

Object

Yes

values[].document.type

APL document type.
Valid value: Link.

String

Yes

values[].document.src

APL document link.
Valid value: doc://alexa/apl/documents/enterprise/suggestions/home/defaultTemplate

String

Yes

values[].datasources

Use to bind data to the APL document.

Map of Data Source objects

Yes

values[].datasources.displayText.title

Text to render in the title field of the document.
Alexa displays the text in a large font on the home screen.
Valid values: Up to 25 characters.

String

No

values[].datasources.displayText.body

Text to render in the body field of the document.
Alexa displays the text in a smaller font below the title on the home screen.
Valid values: Up to 60 characters.

String

No

Placement object

The Placement object defines where to render the suggestion on the screen.

Property Description Type Required

channel

Name of the channel.
At this time, you can place the suggestion on the home screen on Alexa multimodal devices.
Valid values: HOME.

String

Yes

Scheduling object

The Scheduling object defines the schedule to activate the campaign.

Property Description Type Required

activationWindow

Specifies the time in which a campaign is active. If not included in a request, Alexa uses default values.

Object

No

activationWindow.start

Start time of the activation window.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.
Default: Current time.

String

No

activationWindow.end

End of the time of the activation window.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.
Default: 24 hours after the current time.

String

No

Target object

The Target object defines either users or skills that the campaign targets.

Property Description Type Required

type

Type of targeting criteria to apply.
Valid values: USERS, SKILL_SUBSCRIBERS.

String

Yes

values[]

List of user IDs.
This list must contain exactly one user ID.
Valid for type = USERS only.

Array of strings

Yes

values[].id

User ID formatted as amzn1.ask.account.{id}.

String

Yes

Was this page helpful?

Last updated: May 29, 2024