Proactive Events API Reference
You can use the Proactive Events API to send events to Alexa. The events represent factual data that might interest a customer. Upon receiving an event, Alexa proactively delivers the information to customers who have chosen to receive these events. This API currently supports one proactive channel, Alexa Notifications. As more proactive channels are added in the future, you will be able to use them without requiring integration with a new API.
Because customers can choose to be notified of events from your skill, they are never surprised to receive proactive messages from Alexa. With this API, you can send a personal customer-specific event, which results in a notification for a single customer. Alternatively, you can send a broadcast event, which triggers notifications to all customers who have chosen to receive notifications from your skill. For example, a weather skill can send a single weather alert, which Alexa then delivers to all interested customers.
Try Skill demo for proactive events to create a sample skill that uses proactive events.
- Add proactive events to your skill
- Migrate from the Notifications API
- Understand events and schemas
- Add localization support
- Define proactive events with SMAPI
- Prepare to send proactive events to Alexa
- Call the Proactive Events API
Add proactive events to your skill
Here is the high-level process for adding proactive events to your skill.
- Select schemas to represent the events you want to send to users.
- Update the skill manifest with Proactive Events capability. For more information, see Define proactive events with SMAPI.
- Update your skill service to send proactive events to the user when certain conditions occur, such as when an order is delivered.
- Set up your Alexa device as an end user of your skill, so you can test the customer experience. In the Notifications settings page in the Alexa app, enable notifications for your skill. This is so you provide the required permissions to receive proactive events as an end user. When your skill is available publicly, your customers must similarly enable Notifications in the Alexa app so that the proactive events notifications to work for them, and they will be prompted to make this change in the Alexa app when they use your skill.
- Open the Test section of the developer console. Test the skill as if you were an end user. Send a proactive event and ensure you receive the notification on your Alexa-enabled device. For more information, see Prepare to send proactive events to Alexa and Calling the ProactiveEvents API.
- Submit your skill for certification. For more information, see Test and Submit Your Skill for Certification. When certification is complete, customers can access your skill.
Migrate from the Notifications API
If you previously integrated the Notifications API preview with your skill, you can migrate the skill to the Proactive Events API and then submit the skill for re-certification. After certification, Amazon automatically subscribes customers who had enabled notifications in your skill to proactive events that you declare. Whenever you add a new event type to your skill manifest, Amazon subscribes those customers who had previously enabled a relevant notification to the new event type.
Understand events and schemas
You can add support for proactive events to your skill when you configure your skill through SMAPI (Skill Management API), as described in Define proactive events with SMAPI.
You can choose the proactive event schemas that you want to support from a list of pre-defined schemas. These schemas represent the events you want to notify your customers about. In your skill service, you use the Proactive Events API to send these events to the customer as appropriate. In the Alexa app, if a customer chooses to receive notifications from your skill, the customer will then receives a notification for each event. For more information, see Schemas for Proactive Events.
You can implement only one instance of each schema.
The following example shows an AMAZON.OrderStatus.Updated
event that represents the status of an order.
{
"timestamp": "2019-04-18T03:27:00.00Z",
"referenceId": "mytest-request-id",
"expiryTime": "2019-04-19T10:00:00.00Z",
"event": {
"name": "AMAZON.OrderStatus.Updated",
"payload": {
"state": {
"status": "ORDER_SHIPPED",
"deliveryDetails": {
"expectedArrival": "2019-04-19T12:03:00.000Z"
}
},
"order": {
"seller": {
"name": "localizedattribute:sellerName"
}
}
}
},
"localizedAttributes": [
{
"locale": "en-US",
"sellerName": "Example Corp."
}
],
"relevantAudience": {
"type": "Unicast",
"payload": {
"user": "amzn1.ask.account.<identifier>"
}
}
}
When your skill delivers an event to a customer, the event is merged with a predefined template that represents the text read back to the end user by Alexa.
The following example shows the template for this schema:
"Your order from Example Corp. has been shipped and will arrive by Monday, December 12."
If you need other schemas for your skills, enter your request at Alexa Skills - User Voice and Vote.
Add localization support
The Proactive Events API allows for localized content in the localizedAttributes
field, which is external to the event. The API references the localized content from the body of the event. All ENUM values are automatically localized. The names of the event
fields are never localized.
The following example shows how you can communicate a localized resource for the event.payload.weatherAlert.source
value in the event AMAZON.WeatherAlert.Activated
. In this case, localizedAttributes
has only a single locale in the array, but you can add additional elements to the localizedAttributes
array to support additional locales if appropriate.
{
"event": {
"name": "AMAZON.WeatherAlert.Activated",
"payload": {
"weatherAlert": {
"source": "localizedattribute:source",
"alertType": "TORNADO"
}
}
},
"localizedAttributes": [
{
"locale": "en-US",
"source": "Example Weather Corp"
}
]
}
Define proactive events with SMAPI
With the Skill Management API (SMAPI), you can define the events your skill provides to your customers.
You define events as part of the skill manifest. You can create, read, and delete events through the Skill Management API (SMAPI). To modify your skill's manifest using SMAPI, see Skill Manifest REST API Reference.
The skill manifest includes the events.publications
object to support defining events. The events.subscriptions
object indicates customer subscription changes, and is optional.
The manifest must also include the permissions
object, and must contain alexa::devices:all:notifications:write
as a permissions.name
value, as shown in the following example.
Your manifest must specify the proactive events that you are including in your skill. In this example, these are AMAZON.OrderStatus.Updated
and AMAZON.MessageAlert.Activated
.
"permissions": [
{
"name": "alexa::devices:all:notifications:write"
}
],
"events": {
"publications": [
{
"eventName": "AMAZON.OrderStatus.Updated"
},
{
"eventName": "AMAZON.MessageAlert.Activated"
}
],
"endpoint": {
"uri": "arn:aws:lambda:us-east-1:0000000000000:function:sampleSkill"
},
"subscriptions": [
{
"eventName": "SKILL_PROACTIVE_SUBSCRIPTION_CHANGED"
}
],
"regions": {
"NA": {
"endpoint": {
"uri": "arn:aws:lambda:us-east-1:0000000000000:function:sampleSkill"
}
}
}
}
For more information, see Skill manifest events.
Prepare to send proactive events to Alexa
To call the API, you can authenticate with Alexa as follows.
Request format to obtain access token
The following sections describe the format for the POST request to obtain an access token.
HTTP header
POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Parameters of HTTP header
Parameter | Description | Example |
---|---|---|
Content-Type |
Content type of the resource. Must be application/x-www-form-urlencoded .
|
Content-Type: application/x-www-form-urlencoded
|
Request body syntax
grant_type=client_credentials&client_id=(clientID)&client_secret=(clientSecret)&scope=alexa::proactive_events
Request body parameters
Parameter | Description | Example |
---|---|---|
grant_type |
Value must be client_credentials . |
grant_type=client_credentials
|
client_id |
ClientId value from the developer console. |
client_id=xxxx |
client_secret
|
ClientSecret value from the developer console. |
client_secret=xxxx |
scope |
Value must be alexa::proactive_events . |
scope=alexa::proactive_events |
Locate ClientId and ClientSecret values
First, ensure that you have deployed your skill with a manifest that has Notifications permissions enabled.
You can then access the ClientId
and ClientSecret
in several ways:
- Select the skill in the developer console. Next, select the Build tab, scroll down to the Permissions section, and locate the
ClientId
andClientSecret
values from the Alexa Skill Messaging section at the bottom of the page. - Use the Skill Credential API to access the
ClientId
andClientSecret
values. - Use the ASK CLI get-skill-credentials smapi subcommand.
Example cURL request
curl -i -XPOST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=xxxx&client_secret=yyyy&scope=alexa::proactive_events' https://api.amazon.com/auth/o2/token
Response format
The following sections describe the format of the response to the POST request seeking an access token.
HTTP header
X-Amzn-RequestId: d917ceac-2245-11e2-a270-0bc161cb589d
Content-Type: application/json
Parameters of HTTP header
Parameter | Description | Example |
---|---|---|
X-Amzn-RequestId |
Value created by the server that uniquely identifies the request. If you have problems, Amazon can use this value to troubleshoot. | X-Amzn-RequestId: d917ceac-2245-11e2-a270-0bc161cb589d |
Content-Type |
Content type of the resource: application/json |
Content-Type: application/json |
Response body syntax
{
"access_token":"Atc|MQEWYJxEnP3I1ND03ZzbY_NxQkA7Kn7Aioev_OfMRcyVQ4NxGzJMEaKJ8f0lSOiV-yW270o6fnkI",
"expires_in":3600,
"scope":"alexa::proactive_events",
"token_type":"Bearer"
}
Parameters of response body
Parameter | Description | Example |
---|---|---|
access_token |
Access token that must be used for all requests. | access_token”:“Atc|MQEWYJxEnP3I1ND03Zz… |
expires_in |
Duration in seconds of the access token lifetime. For example, 3600 denotes that the access token expires in one hour from the time the response was generated. | "expires_in":3600 |
scope |
Scope specified in the access token request. Value is alexa::proactive_events . |
"scope":"alexa::proactive_events"
|
token_type |
Type of the token issued. Only Bearer tokens are supported. | "token_type":"Bearer"
|
If your request is not successful, you receive a non-200 error status code. In the case of a non-200 code, the response message might contain the following parameter in the body of the JSONObject.
reason: « The reason the request was not accepted. »
Error handling: Status codes
Status Code | Type | Description |
---|---|---|
400 | INVALID_REQUEST
|
Reasons for this response include:
|
400 | UNAUTHORIZED_CLIENT
|
Client is not authorized for the requested operation. |
400 | UNSUPPORTED_GRANT_TYPE
|
Grant type is not supported by the authorization server. In other words, it is not client_credentials .
|
400 | INVALID_SCOPE
|
Requested scope is invalid, which means it is not alexa::proactive_events .
|
401 | INVALID_CLIENT
|
Client authentication failed. |
500 | SERVER_ERROR
|
Server error. |
503 | SERVICE_UNAVAILABLE
|
Server is temporarily unavailable. The requester must retry later honoring the Retry-After header included in the response. For possible formats for the Retry-After value, see the HTTP/1.1 specification.
|
Call the Proactive Events API
Development endpoints
While you are developing your skill, you can test it by sending proactive events using the following development endpoints. These endpoints are always available to you, and you can use them without any risk of sending requests to your live customers. Use the Notifications settings in the Alexa app to subscribe to receive test notifications.
Select the appropriate endpoint for your region:
https://api.amazonalexa.com/v1/proactiveEvents/stages/development (North America)
https://api.eu.amazonalexa.com/v1/proactiveEvents/stages/development (Europe)
https://api.fe.amazonalexa.com/v1/proactiveEvents/stages/development (Far East)
Production endpoints
To send events to your live customers, send proactive events to the appropriate live endpoint. These endpoints are only available to you once your skill is certified, and they only accept events that your skill has been certified to send to Alexa.
Select the appropriate endpoint for your region:
https://api.amazonalexa.com/v1/proactiveEvents/ (North America)
https://api.eu.amazonalexa.com/v1/proactiveEvents/ (Europe)
https://api.fe.amazonalexa.com/v1/proactiveEvents/ (Far East)
By using the access token you received in Request format to obtain access token, you can have your skill call the Proactive Events API as follows.
Method | POST |
---|---|
URI | /v1/proactiveEvents/ |
Request headers |
Content-type: application/json
Authorization: Bearer << accessToken >>
|
Create individual events
You can have your skill create individual events, which are directed at a specific user, or broadcast events, which are directed to all users.
For an individual event, include a type
value of Unicast
, and include the specific userId
parameter in the relevantAudience
object in the request, as shown in the following example.
{
"timestamp": "2018-06-18T22:10:01.00Z",
"referenceId": "unique-id-of-this-instance",
"expiryTime": "2018-06-19T22:10:01.00Z",
"event": "<event_payload>",
"localizedAttributes": "[array of localized attributes]",
"relevantAudience": {
"type": "Unicast",
"payload": {
"user": "userId"
}
}
}
Create broadcast events
For a broadcast event, which is directed to all users, include a type
value of "Multicast" in the relevantAudience
object in the request, as shown in the following example.
{
"timestamp": "2018-06-18T22:10:01.00Z",
"referenceId": "unique-id-of-this-instance",
"expiryTime": "2018-06-19T22:10:01.00Z",
"event": "<event_payload>",
"localizedAttributes": "[array of localized attributes]",
"relevantAudience": {
"type": "Multicast",
"payload": {}
}
}
Proactive Events API parameters
Here are the parameters for the Proactive API.
Parameter | Type | Required | Description |
---|---|---|---|
timestamp |
string | Mandatory | Date and time of the event associated with this event, in ISO 8601 format. Represents the time when the event was created. |
referenceId |
string | Mandatory | Client-supplied ID for correlating the event with external entities. This field is also used as the idempotent key for creating events. For more information, see Idempotency of events. The allowed characters for the referenceId field are alphanumeric and ~ , and the length of the referenceId field must be 1-100 characters. |
expiryTime |
string | Mandatory | Date and time, in ISO 8601 format, when the service automatically moves the notification from Recent to Previous . The maximum allowed expiryTime value is 24 hours, and the minimum is 5 minutes. |
event |
object | Mandatory | Event data to be sent to customers, conforming to the schema associated with this event. |
localizedAttributes |
array | Mandatory | List of items that each contains the set of event attributes that requires localization support. See Add localization support for details. |
relevantAudience |
object | Mandatory | Audience for this event. |
relevantAudience.type |
enum | Mandatory | Audience for this event. Use Multicast to target information to all customers subscribed to that event, or use Unicast to target information containing the actual userId for individual events. |
relevantAudience.payload |
object | Mandatory | If relevantAudience.type is set to Multicast , then the payload object is empty, but still required. |
relevantAudience.payload.user |
string | Mandatory, if relevantAudience.type is set to Unicast . |
The userId value for which the event is targeted. |
Update events
To update an event, use the same referenceId
, but a different timestamp
. The latest timestamp replaces any earlier instance of an event.
Input validation
Your inputs must be valid. If any of the following input validation tests fail, a status code of 400 (Bad Request) is returned.
- All required fields are present. All fields must contain values. Null values are not permitted.
- Locales must be in IETF BCP 47 format.
- Dates and times must be in ISO 8601 format.
Idempotency of events
The Proactive Events API is idempotent based on a client-provided referenceId
, in combination with the skillId
and customerId
. This means that a repeated call with these same parameters will have the same result.
Although a referenceId
must be unique for a particular skill and customer combination, a skill can use the same referenceId
value to create an event for a different customer. Similarly, a customer can have events published by different skills with the same referenceId
value.
Error handling: Status codes
The following table lists the error status codes that might occur when a request is sent to Alexa.
Status | Code | Description |
---|---|---|
400 | Bad request. | Returned when a required parameter is not present or is incorrectly formatted, or the requested creation of a resource was already completed by a previous request. |
403 | Unauthorized | Returned when authentication fails. |
409 | Conflict | Returned, for example, when a skill attempts to create duplicate events using the same referenceId for the same customer. |
429 | Too many requests | Returned when the client has made more calls than the allowed limit. Limit is 25 tps per skill. |
432 | Too many requests for customer | Too many notifications for customer. |
500 | Internal server error | Returned when the ProactiveEvents API encounters an internal server error for a valid request. |
Subscription events
When a customer subscribes to receive events from your skill, Alexa sends a message to your skill containing information for that user. You need this information to know the userId
in order to send events to individual users. In order to subscribe to events, the customer must first enable Notifications in the Alexa app for your skill.
To configure your skill to receive these event, see Skill events.
Event format
The event published back to your skill has the following format. The list of subscriptions contains the list of events to which a customer is currently subscribed. If a customer unsubscribes from an event, this list contains the remaining event types that the customer is still subscribed to receive from your skill. If the list of subscriptions is empty, this customer has unsubscribed from all event types from your skill.
{
"version": "string",
"context": {
"System": {
"application": {
"applicationId": "string"
},
"user": {
"userId": "string"
},
"apiEndpoint": "https: //api.amazonalexa.com"
}
},
"request": {
"type": "AlexaSkillEvent.ProactiveSubscriptionChanged",
"requestId": "string",
"timestamp": "string",
"body": {
"subscriptions": [
{
"eventName": "string"
}
]
}
}
}
Last updated: Jan 03, 2023