Proactive Events REST API Reference
Use the Proactive Events REST API to create or update events that you want Alexa to deliver to your customers. The event information must be factual data that might interest customers. Alexa sends the event information as notifications to customers that have granted permission to receive notifications. For more details, see About Proactive Events.
HTTP 432
. Notification limits apply to live skills, not to skills in development that use the API development endpoints.API endpoint
As you develop your skill, you can test it by sending API requests to the Proactive Events development endpoints. You can use these endpoints without risk of sending notifications to customers. Before you publish your skill, change the endpoints to the production endpoints.
Development endpoints
During development, test proactive events by sending the API to the development endpoints. Use the Notifications settings in the Alexa app to subscribe to receive test notifications.
Use one of the following API hosts, based on the region where the tester is located:
- North America:
https://api.amazonalexa.com/v1/proactiveEvents/stages/development
- Europe:
https://api.eu.amazonalexa.com/v1/proactiveEvents/stages/development
- Far East:
https://api.fe.amazonalexa.com/v1/proactiveEvents/stages/development
Production endpoints
After Amazon certifies your skill, use one of the following API hosts, based on the region where the customer is located:
- North America:
https://api.amazonalexa.com/v1/proactiveEvents/
- Europe:
https://api.eu.amazonalexa.com/v1/proactiveEvents/
- Far East:
https://api.fe.amazonalexa.com/v1/proactiveEvents/
Authentication
Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA) by using the alexa::proactive_events
scope. For details, see Get an Access Token for SMAPI.
Operations
The Proactive Events API includes the following operations.
Operation | HTTP method and URI |
---|---|
| |
|
Create event
Create a new event. You can create individual events directed at a specified customer, or broadcast events directed to all customers that enable proactive events.
Request
To create an event, you make a POST
request to the proactiveEvents
resource.
Request path and header example
POST /v1/proactiveEvents
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Header |
String |
Yes |
Request body example
The following example shows a request to create an individual event that uses the AMAZON.OrderStatus.Updated
schema.
The following example shows a request to create a multicast event that uses the AMAZON.WeatherAlert.Activated
schema.
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Date and time of the event. |
String |
Yes |
|
ID used to correlate the event with external entities. Must be unique for specific skill and customer. You can use the same |
String |
Yes |
|
Date and time to delete the event if the event is still in the pending state. |
String |
Yes |
|
Data to be sent to customers in the event. |
Object |
Yes |
|
Specifies the proactive event template. |
String |
Yes |
|
Data to send in the notification. For a list of payload parameters for the selected event template, see Event catalog. |
Object |
Yes |
|
List of event attributes that require localization. Alexa localizes all |
Object |
Yes |
|
Specifies the locale to use. Alexa tries to match the locale based on the language and region on the device settings of the customer. |
String |
Yes |
|
List of event attributes that require localization. |
Object |
Yes |
|
Defines the target audience for this event. |
Object |
Yes |
|
Indicates whether to send the event to a single customer or all customers. |
String |
Yes |
|
For |
Object |
Yes |
|
Identifies the user that subscribes to proactive events. Use the |
Object |
No |
Response
A successful response returns HTTP 202 Accepted
to indicate that Alexa created the event successfully.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Request to create an event succeeded. |
|
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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Skill has exceeded the permitted notification limit to a single customer. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update event
Update an existing event. You can update individual events directed at a specified customer, or broadcast events directed to all customers that enable proactive events.
To update an event, use the same referenceId
as the original event with a different timestamp
value. The latest timestamp replaces earlier instances of this event.
Request
To update an event, you make a POST
request to the proactiveEvents
resource.
Request path and header example
POST /v1/proactiveEvents
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Header |
String |
Yes |
Request body example
The following example shows a request to update an individual event that uses the AMAZON.OrderStatus.Updated
schema.
{
"timestamp": "2023-06-22T22:10:01.00Z",
"referenceId": "unique.reference.id.1",
"expiryTime": "2023-06-23T22:10:01.00Z",
"event": {
"name": "AMAZON.OrderStatus.Updated",
"payload": {
"state": {
"status": "ORDER_DELIVERED",
"deliveryDetails": { }
},
"order": {
"seller": {
"name": "localizedattribute:sellerName"
}
}
}
},
"localizedAttributes": [{
"locale": "en-US",
"sellerName": "AnyCompany"
}],
"relevantAudience": {
"type": "Unicast",
"payload": {
"user": "amzn1.ask.account.1"
}
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Date and time of the updated event. Use a later timestamp to update an existing event. |
String |
Yes |
|
Identifies the event to update. Use an existing event |
String |
Yes |
|
Date and time to delete the event if the event is still in the pending state. |
String |
Yes |
|
Defines the event schema and data to send. |
Object |
Yes |
|
Specifies the proactive event template. |
String |
Yes |
|
Data to send in the notification to customers. For a list of payload parameters for the selected event template, see Event catalog. |
Object |
Yes |
|
List of event attributes that require localization. Alexa localizes all |
Object |
Yes |
|
Specifies the locale to use. Alexa tries to match the locale based on the language and region on the device settings of the customer. |
String |
Yes |
|
List of event attributes that require localization. |
Object |
Yes |
|
Defines the target audience for this event. |
Object |
Yes |
|
Indicates whether to send the event to a single customer or all customers. |
String |
Yes |
|
For |
Object |
Yes |
|
Identifies the user that subscribes to proactive events. Use the |
Object |
No |
Response
A successful response returns HTTP 202 Accepted
to indicate that Alexa updated the event successfully.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Request to update an event succeeded. |
|
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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Skill has exceeded the permitted notification limit to a single customer. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Object definitions
The Proactive Events API defines the following object definitions.
Locale values
Set the locale
property to a locale code valid for the event. The following table shows valid values for the locale property.
Locale code | Language |
---|---|
|
Arabic (SA) |
|
German (DE) |
|
English (AU) |
|
English (CA) |
|
English (UK) |
|
English (IN) |
|
English (US) |
|
Spanish (ES) |
|
Spanish (MX) |
|
Spanish (US) |
|
French (CA) |
|
French (FR) |
|
Hindi (IN) |
|
Italian (IT) |
|
Japanese (JP) |
|
Dutch (NL) |
|
Portuguese (BR) |
Related topics
Last updated: Nov 29, 2023