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.

1. Select schemas to represent the events you want to send to users.
2. Update the skill manifest with Proactive Events capability. For more information, see Define proactive events with SMAPI.
3. Update your skill service to send proactive events to the user when certain conditions occur, such as when an order is delivered.
4. 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.
5. 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.
6. 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.

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.

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.

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 and ClientSecret values from the Alexa Skill Messaging section at the bottom of the page.
• Use the Skill Credential API to access the ClientId and ClientSecret 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

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: Content type is not supported by the authorization server. In other words, it is not application/x-www-form-urlencoded. Request is missing at least one required parameter: grant-type, scope, client_id, client_secret Request is otherwise malformed.
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.

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.

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.

---

Last updated: Jan 03, 2023