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.

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

POST /v1/proactiveEvents

Update event

POST /v1/proactiveEvents

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

Copied to clipboard.

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

access token

Header

LWA token.

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

timestamp

Date and time of the event.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

Yes

referenceId

ID used to correlate the event with external entities. Must be unique for specific skill and customer. You can use the same referenceId value for the same event to a different customer.
Valid values: 1 – alphanumeric characters and ~.

String

Yes

expiryTime

Date and time to delete the event if the event is still in the pending state.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.
Valid values: 5 minutes – 24 hours.

String

Yes

event

Data to be sent to customers in the event.

Object

Yes

event.name

Specifies the proactive event template.
Valid values: Event catalog

String

Yes

event.payload

Data to send in the notification. For a list of payload parameters for the selected event template, see Event catalog.

Object

Yes

localizedAttributes

List of event attributes that require localization. Alexa localizes all ENUM values by default.

Object

Yes

localizedAttributes.locale

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

localizedAttributes.source

List of event attributes that require localization.

Object

Yes

relevantAudience

Defines the target audience for this event.

Object

Yes

relevantAudience.type

Indicates whether to send the event to a single customer or all customers.
Valid values: Unicast, Multicast.

String

Yes

relevantAudience.payload

For Unicast events, defines the customer to which to send the event. If you set type to Multicast, include an empty payload object.

Object

Yes

relevantAudience.payload.userId title: Use Skill Events

Identifies the user that subscribes to proactive events. Use the userId from skill events.

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

202 Accepted

Request to create an event succeeded.

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

432 Too Many Requests for Customer

Skill has exceeded the permitted notification limit to a single customer. 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.

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

Copied to clipboard.

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

access token

Header

LWA token.

String

Yes

Request body example

The following example shows a request to update an individual event that uses the AMAZON.OrderStatus.Updated schema.

Copied to clipboard.

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

timestamp

Date and time of the updated event. Use a later timestamp to update an existing event.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

Yes

referenceId

Identifies the event to update. Use an existing event referenceId.
Valid values: 1 – alphanumeric characters and ~.

String

Yes

expiryTime

Date and time to delete the event if the event is still in the pending state.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.
Valid values: 5 minutes – 24 hours.

String

Yes

event

Defines the event schema and data to send.

Object

Yes

event.name

Specifies the proactive event template.
Valid values: Event catalog

String

Yes

event.payload

Data to send in the notification to customers. For a list of payload parameters for the selected event template, see Event catalog.

Object

Yes

localizedAttributes

List of event attributes that require localization. Alexa localizes all ENUM values by default.

Object

Yes

localizedAttributes.locale

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

localizedAttributes.source

List of event attributes that require localization.

Object

Yes

relevantAudience

Defines the target audience for this event.

Object

Yes

relevantAudience.type

Indicates whether to send the event to a single customer or all customers.
Valid values: Unicast, Multicast.

String

Yes

relevantAudience.payload

For Unicast events, defines the customer to which to send the event. If you set type to Multicast, include an empty payload object.

Object

Yes

relevantAudience.payload.userId title: Use Skill Events

Identifies the user that subscribes to proactive events. Use the userId from skill events.

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

202 Accepted

Request to update an event succeeded.

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

432 Too Many Requests for Customer

Skill has exceeded the permitted notification limit to a single customer. 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 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

ar-SA

Arabic (SA)

de-DE

German (DE)

en-AU

English (AU)

en-CA

English (CA)

en-GB

English (UK)

en-IN

English (IN)

en-US

English (US)

es-ES

Spanish (ES)

es-MX

Spanish (MX)

es-US

Spanish (US)

fr-CA

French (CA)

fr-FR

French (FR)

hi-IN

Hindi (IN)

it-IT

Italian (IT)

ja-JP

Japanese (JP)

nl-NL

Dutch (NL)

pt-BR

Portuguese (BR)
Was this page helpful?

Last updated: Nov 29, 2023