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 Submit Skills for Certification in the Alexa Developer Console. 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

You define events as part of the skill manifest. You can create, read, and delete events by using the 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 Get access token with skill credentials operation to retrieve the access token from Login with Amazon (LWA) OAuth server. In the request body, set the scope to scope=alexa::proactive_events.

Example cURL request

curl -i -XPOST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=your.client.id&client_secret=your.client.secret&scope=alexa::proactive_events' https://api.amazon.com/auth/o2/token

Create proactive events

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

Development endpoints

During skill development, you can test your skill code 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.

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: Aug 07, 2024