Your Alexa Consoles

Proactive Events API

The ProactiveEvents API enables Alexa Skill Developers to send events to Alexa, which represent factual data that may interest a customer. Upon receiving an event, Alexa proactively delivers the information to customers subscribed to receive these events. This API currently supports one proactive channel, Alexa Notifications. As more proactive channels are added in the future, developers will be able to take advantage of them without requiring integration with a new API.

Customers subscribe to be notified of events they are interested in, ensuring they are never surprised with proactive messages from Alexa. With this API, developers can send a personal customer-specific event, which results in a notification for a single customer, or a broadcast event, which triggers notifications to all customers subscribed to that event. For example, a weather skill can send a single weather alert, which Alexa then delivers to all interested customers.

Process to add proactive events to your skill
Migration from the Notifications API
Events and schemas
Localization support representation
Onboard with proactive events using SMAPI
Prepare to send proactive events to Alexa
Call the ProactiveEvents API

Process to add 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. See Onboard with proactive events using SMAPI.
In the Notifications settings page in the Alexa app, enable notifications for your skill.
Send a proactive event and ensure you receive the notification on your Alexa-enabled device. See Prepare to send proactive events to Alexa and Calling the ProactiveEvents API.
Submit your skill for certification.

Migration from the Notifications API

If you have integrated with the Notifications API that was previously offered in extended preview mode, you can migrate over to the ProactiveEvents API. After your skill is certified with ProactiveEvents capabilities, customers who had previously enabled notifications for your skill will automatically be subscribed to the proactive events you declare in your skill.

Additionally, whenever you add a new event type to your skill manifest, the migration will also be performed after your skill is certified in order to ensure customers receive the new event type you declare.

Note: It may take up to 48 hours for the migration to complete from the time your skill has been certified with ProactiveEvents capabilities.

Events and schemas

Developers select schemas to represent the events they want to notify their customers about, and send these events to the ProactiveEvents API. Customers subscribed to receive notifications about these events from the skill will then receive an Alexa notification. Schemas are pre-defined by the Alexa Skills Kit. See Schemas for Proactive Events.

Your skill can use different schemas to represent different themes about which you want to engage their customers. Your skill cannot implement multiple instances of the same schema.

To get started, you must first add the Proactive Events capability when configuring your skill through SMAPI (Skill Management API). When configuring events that you want your skill to send, you must choose from a pre-defined set of schema definitions that describe the event.

Here is a sample event that represents the status of an order:

{
    "url": "https://api.amazonalexa.com/v1/proactiveEvents/stages/development",
    "json": {
        "timestamp": "2018-12-14T00:20:24.119Z",
        "referenceId": "OrangeCatReferenceId1544746824119",
        "expiryTime": "2018-12-14T00:30:24.119Z",
        "event": {
            "name": "AMAZON.OrderStatus.Updated",
            "payload": {
                "state": {
                    "status": "ORDER_SHIPPED",
                    "deliveryDetails": {
                        "expectedArrival": "2018-12-14T23:32:00.463Z"
                    }
                },
                "order": {
                    "seller": {
                        "name": "localizedattribute:sellerName"
                    }
                }
            }
        },
        "localizedAttributes": [
            {
                "locale": "en-US",
                "sellerName": "United States"
            },
            {
                "locale": "en-GB",
                "sellerName": "England"
            },
            {
                "locale": "en-IN",
                "sellerName": "India"
            },
            {
                "locale": "en-AU",
                "sellerName": "Australia"
            },
            {
                "locale": "en-CA",
                "sellerName": "Canada"
            }
        ],
        "relevantAudience": {
            "type": "Unicast",
            "payload": {
                "user": <userId>Or
            }
        }
    },
    "headers": {
        "Authorization": "bearer <token>"
    }
}

When the event is delivered to customers, it is merged with a predefined template that represents the text read back to the end user by Alexa.

Here is a sample template for this schema:

"Your order from The Company has been shipped and will arrive by Monday 12th December."

If you have a use case that does not have a corresponding schema, please enter your request at Alexa Skills - User Voice and Vote. We are adding schemas on an ongoing basis.

Localization support representation

The localized content is encapsulated the localizedAttributes field, and is external to the event. The localized content is referenced from the body of the event. All ENUM values will automatically be localized.

For example, here is how a localized resource is communicated for the event AMAZON.WeatherAlert.Activated:

{
    ...
    "event": {
        "name": "AMAZON.WeatherAlert.Activated",
        "payload": {
            "weatherAlert": {
                "source": "localizedattribute:weatherAlertSource",
                "alertType": "TORNADO"
            }
        }
    },
    "localizedAttributes": [
        {
            "locale": "en-US",
            "weatherAlertSource": "Weather Channel"
        },
        {
            "locale": "fr-FR",
            "weatherAlertSource": "Canal météo"
        }
    ]
    ...
}

Onboard with proactive events using SMAPI

By using SMAPI, you can define the events your skill will provide to your customers.

Events are defined as part of the skill manifest. Events can be created/read/deleted through the Skill Management API (SMAPI). See SMAPI skill operations to modify your skill’s manifest using SMAPI.

The publications object has been added to the events section of the skill manifest to support defining events. When specifying event publications you must include alexa::devices:all:notifications:write as a permission, as shown in the following example. This example also includes two proactive events: 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:040623927470:function:sampleSkill"
    },
    "subscriptions": [
      {
        "eventName": "SKILL_PROACTIVE_SUBSCRIPTION_CHANGED"
      }
    ],
    "regions": {
      "NA": {
        "endpoint": {
          "uri": "arn:aws:lambda:us-east-1:040623927470:function:sampleSkill"
        }
      }
    }
  } 

Field	Description	Type
events	Top-level object which contains one or more events supporting the declaration of a skill.	Object
events.publications	Contains an array of `eventName` objects, each of which contains the name of an event supported by the ProactiveEvents API.	Array
events.publications.eventName	The name of an event supported by the ProactiveEvents API.	Enum

Prepare to send proactive events to Alexa

To call the API, you can authenticate with Alexa as follows.

Request format to obtain access token

This section documents 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	The 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	The ClientId value from the developer console.	client_id=amzn1.iba-client.b2b360f8a77d457981625636121d6edf
client_secret	The ClientSecret value from the developer console.	client_secret=c559965801308f2bb79ca787b1dfc8deece8a2fd7d7618946cec1635d26dcbfb
scope	Value must be alexa::proactive_events	scope=alexa::proactive_events

To locate ClientId and ClientSecret in the developer console, select the Build tab, scroll down to the Permissions section, and get these values from Alexa Skill Messaging at the bottom right.

Sample cURL request

curl -k -X POST -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

This section documents 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	A 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	The 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	An access token that must be used for all requests.	"access_token":"Atc\|MQEWYJxEnP3I1ND03Zz…"
expires_in	The 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	The scope specified in the access token request. Value will be `alexa::proactive_events`.	"scope":"alexa::proactive_events"
token_type	The type of the token issued. Only Bearer tokens are supported.	"token_type":"Bearer"

If your request is not successful, you will receive a non-200 error status code. In the case of a non-200 code, the response message may 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: The content type is not supported by the authorization server. In other words, it is not application/x-www-form-urlencoded. The request is missing at least one required parameter: `grant-type`, `scope`, `client_id`, `client_secret` The request is otherwise malformed.
400	UNAUTHORIZED_CLIENT	The client is not authorized for the requested operation.
400	UNSUPPORTED_GRANT_TYPE	The grant type is not supported by the authorization server. In other words, it is not `client_credentials`.
400	INVALID_SCOPE	The requested scope is invalid, which means it is not `alexa::proactive_events`.
401	INVALID_CLIENT	The client authentication failed.
500	SERVER_ERROR
503	SERVICE_UNAVAILABLE	The server is temporarily unavailable. The requester must retry later honoring the Retry-After header included in the response. See the HTTP/1.1 specification, Retry-After, for possible formats for the Retry-After value.

Call the ProactiveEvents API

While your skill is in the development stage, you can test it by sending proactive events using the following development endpoint. This endpoint is always available to you, and you can use it without concerns of sending requests to your live customers. Use the Notifications settings in the Alexa app to subscribe to receive test notifications.

https://api.amazonalexa.com/v1/proactiveEvents/stages/development

To send events to your live customers, send proactive events to the live endpoint. This endpoint is only available to you once your skill is certified, and it only accepts 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)

A skill can call the ProactiveEvents API as follows, using the access token you received from the previous step.

Method	POST
URI	`/v1/proactiveEvents[/stages/development]`
Request headers	`Content-type: application/json Authorization: Bearer << accessToken >>`

Create individual events

Events can be either individual, if directed at a specific user, or broadcast, if 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"
    }
}

API parameters

Parameter	Type	Required	Description
timestamp	string	Mandatory	The 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. 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	The date and time, in ISO 8601 format, when the service will automatically delete the notification if it is still in the pending state. The maximum allowed `expiryTime` value is 24 hours, and the minimum is 5 minutes.
event	object	Mandatory	The event data to be sent to customers, conforming to the schema associated with this event.
localizedAttributes	array	Optional	A list of items which each contains the set of event attributes that requires localization support. See Multi-Locale Content Support section below for details.
relevantAudience	object	Mandatory	The audience for this event. Use `Multicast` to target information to all customers subscribed to that event, or use `Unicast` to target information containing actual userId for individual events.

Update events

To update an event, use the same referenceId, but a different timestamp. The latest timestamp will replace any earlier instance of an event.

Input validation

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.

If any of these input validation tests fail, a status code of 400 (Bad Request) is returned.

Idempotency of events

The ProactiveEvents API is idempotent based on a client-provided referenceId, in combination with the skillId and customerId.

Although a referenceId must be unique for a particular skill and customer combination, a skill may use the same referenceId value to create an event for a different customer. Similarly, a customer may have events published by different skills with the same referenceId value.

Error handling: Status codes

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 has already been completed by a previous request.
403	Unauthorized	Returned when authentication fails.
409	Conflict	For example, this code is returned 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.
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 will send 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.

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 that this customer is currently subscribed to. If a customer unsubscribes from an event, this list will contain remaining event types to which 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. Note that these events can arrive out of order, so ensure that your skill service uses the timestamp in the event to correctly record the latest subscription state for a customer.

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