About Proactive Events

You can use the Proactive Events REST 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. At this time proactive events supports one proactive channel, Alexa Notifications.

Because customers can choose to be notified of events from your skill, they're 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.

Add proactive events to your skill

Complete the following steps to add proactive events to your skill.

  1. Select the schemas to represent the events that you want to send to users.
  2. Update the skill manifest with Proactive Events capability. For more details, see Define proactive events with SMAPI.
  3. Update your skill service to send proactive events to the customer when certain conditions occur, such as when an order is delivered.
  4. Set up your Alexa device as a user of your skill, so that you can test the customer experience. In the Notifications settings page in the Alexa app, to provide the required permissions for proactive events, enable notifications for your skill. When your skill is available publicly, your customers must similarly enable Notifications in the Alexa app to receive notifications from your skill.
  5. Open the Test section of the developer console. Test the skill as if you were a customer. Send a proactive event and make sure that you receive the notification on your Alexa-enabled device. For more details, see Prepare to send proactive events to Alexa and Calling the ProactiveEvents API.
  6. Submit your skill for certification. For more details, see Test and Submit Your Skill for Certification. When certification is complete, customers can access your skill.

Migrate from the Notifications API

If you 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 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 receives a notification for each event. For more details, see Schemas for Proactive Events.

You can implement one instance of each schema only.

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.1"
    }
  }
}

When your skill creates an event, Alexa merges the event data with a predefined template that represents the text read to the customer.

The following example shows the template for this schema:

"Your order from Example Corp. has been shipped and will arrive by Monday, December 12."

Add localization support

The event schema 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 example, localizedAttributes contains a single locale, 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 include in your skill. In this example, the events 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 details, see Skill manifest events.

Prepare to send proactive events to Alexa

To use the Proactive Events API, you need an access token to authenticate with Alexa. Use the following API to retrieve the access token from Login with Amazon (LWA).

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, make sure that you have deployed your skill with a manifest that has Notifications permissions enabled. Then locate your skill credentials in the Alexa developer console. You use these credentials to get an access token for the Proactive Events API.

You can 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

{
    "access_token":"someToken1",
    "expires_in":3600,
    "scope":"alexa::proactive_events",
    "token_type":"Bearer"
}

Parameters of response body

Parameter Description Example
access_token Access token to use 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 last token 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 isn't 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

Use the Proactive Events REST API to create or update events that you want Alexa to deliver to your customers.

Development endpoints

While you are developing your skill, you can test it by sending proactive events to 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.

Access token

Use the access token that you received in the Request format to obtain access token to call the Proactive Events API as follows.

Input validation

Your inputs must be valid. If any of the following input validation tests fail, Alexa returns an HTTP status code of 400 (Bad Request).

  • All required fields are present. All fields must contain values. Null values aren't permitted.
  • Locales must be in IETF BCP 47 format.
  • Dates and times must be in ISO 8601 format.

Create individual events

You can have your skill create individual events directed at a specific customer, or broadcast events directed to all customers.

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

Update events

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

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.

Subscription events

When a customer subscribes to receive proactive events from your skill, Alexa sends a skill event to your skill containing information for that customer. To send proactive events to individual customers, you need the userId from the permission enabled skill event. To subscribe to proactive events, the customer must first enable Notifications in the Alexa app for your skill.

To configure your skill to receive these permission enabled events, see Skill events.

Event format

The skill event has the following format. The list of subscriptions contains the list of events to which a customer 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"
        }
      ]
    }
  }
}
Was this page helpful?

Last updated: Nov 29, 2023