Gracias por tu visita. Esta página solo está disponible en inglés.

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

  1. Select schemas to represent the events you want to send to users.
  2. Update the Skill Manifest with Proactive Events capability. See Onboard with proactive events using SMAPI.
  3. In the Notifications settings page in the Alexa app, enable notifications for your skill.
  4. 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.
  5. 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.

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:source",
                "alertType": "TORNADO"
            }
        }
    },
    "localizedAttributes": [
        {
            "locale": "en-US",
            "source": "Weather Channel"
        },
        {
            "locale": "fr-FR",
            "source": "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 -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

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 (North America)
https://api.eu.amazonalexa.com/v1/proactiveEvents/stages/development (Europe)
https://api.fe.amazonalexa.com/v1/proactiveEvents/stages/development (Far East)

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",
        "payload": {}
    }
}

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 Mandatory A list of items which each contains the set of event attributes that requires localization support. See Localization support representation below for details.
relevantAudience object Mandatory The audience for this event.
relevantAudience.type enum 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 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 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"
            }]
        }
    }
}