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

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 subscribed 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 choose to subscribe to be notified of events that interest them, 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 subscribed to that event. For example, a weather skill can send a single weather alert, which Alexa then delivers to all interested customers.

You can follow this demo to create a sample skill that uses proactive events, see Skill demo for proactive events.

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 an order being updated.
  4. Set up your Alexa device as an end user, in order to test the skill. 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 order for 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 ProactiveEvents 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 select schemas to represent the events you want to notify your customers about, and send these events to the Proactive Events API. In the Alexa app, customers subscribe to receive notifications about these events from your skill, and then receive an Alexa notification. Alexa Skills Kit pre-defines the schemas. For more information, see Schemas for Proactive Events.

Your skill can use different schemas to represent different themes about which you want to engage their customers. Your customers, in turn, can interact with these different themes. 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.

The following example shows an 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 SMAPI skill operations.

The skill manifest includes the publications object nested in the events object to support defining events. When you specify event publications, you must include alexa::devices:all:notifications:write as a permission, as shown in the following example which also includes two proactive events: AMAZON.OrderStatus.Updated and AMAZON.MessageAlert.Activated.

The manifest must also include the permissions object, and contain alexa::devices:all:notifications:write as a permissions.name value, as shown.

  "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"
        }
      }
    }
  }
Field Description Type
events Top-level object that contains one or more events supporting the declaration of a skill. Object
events.publications Array of eventName objects, each of which contains the name of an event supported by the ProactiveEvents API. Array
events.publications.eventName Enum value that is 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

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=amzn1.iba-client.b2b360f8a77d457981625636121d6edf
client_secret ClientSecret value from the developer console. client_secret=c559965801308f2bb79ca787b1dfc8deece8a2fd7d7618946cec1635d26dcbfb
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 ASK CLI and run the command ask api get-skill-credentials -s {skill-id}.

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:

  • 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
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 ProactiveEvents API

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)

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.

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/stages/development
Request headers Content-type: application/json Authorization: Bearer << accessToken >>

Create individual events

You can have your skill create individul events, that are directed at a specific user, or broadcast events, that 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": {}
  }
}

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 deletes 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 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 Localization support representation below 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

  • 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. 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 may 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.
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"
        }
      ]
    }
  }
}