Send Events to the Alexa Event Gateway

To send a proactive event to Alexa or an asynchronous response to a previous directive, you send an event from your device cloud to the Alexa event gateway. The Alexa.ChangeReport event is the most common proactive event that your skill sends to the Alexa event gateway.

Follow these guidelines to authenticate your smart home skill with the customer account and send asynchronous events to the Alexa gateway.

Prerequisites

To send asynchronous events, your smart home skill must comply with the following prerequisites:

  • Configure account linking for your smart home skill.
  • To send Alexa.ChangeReport events, set proactivelyReported to true in your discovery response for properties of an interface that you report to Alexa.

Event gateway access flow

When the customer enables your smart home skill in the Alexa app, the Alexa service invokes the account linking flow with your OAuth 2.0 provider. Here, the Alexa service obtains access tokens to the customer account in your system. To send events to the Alexa event gateway, a second OAuth exchange occurs. Your skill must implement this OAuth exchange with the Amazon OAuth server.

The Alexa service starts the Alexa event gateway authorization flow by sending an Alexa.Authorization.AcceptGrant directive to your skill. In response, your skill initiates an authorization code-grant flow between your skill and the Login with Amazon (LWA) OAuth server. You store the access tokens for the Alexa customer in a secure location. Later, when you send events and asynchronous responses to the Alexa event gateway on behalf of the customer, you include the access token. Alexa uses the token to identify the Alexa customer.

The following diagram shows the communication flow that your skill implements to send events to the Alexa gateway. Account linking isn't shown. In this example, the diagram shows the ChangeReport event, but you use the same flow for any asynchronous event.

Message flow for AcceptGrant directive, authorization code grant, and ChangeReport.
Click to enlarge

Steps to send events to Alexa

Complete the following steps to enable your skill to send events and asynchronous responses to the Alexa event gateway on behalf of the customer.

  1. Configure permissions in the Alexa developer console.
  2. Add code in your skill to request access to the Alexa event gateway in your skill.
  3. Add code to send events to the Alexa event gateway.

Best practices

To send events and asynchronous responses, implement the following best practices.

  • Provide a Lambda function for each geographic region where you offer your skill. In the developer console, on the Build page, configure specific geographic endpoints for each region that you offer your skill. For details, see Deploy your Lambda function to multiple regions.
  • Obtain and store customer credentials by region. You implement the authorization code grant flow in a region-specific Lambda function. Store the access tokens so that the region-specific Lambda function can access them.
  • Send events to the Alexa event gateway endpoint in the same region as your Lambda function on behalf of customers of that region.
  • To store and send authentication tokens in a secure manner, follow OAuth 2.0 best practices.
  • Exchange the authorization code for the access and refresh tokens right away. The authorization code has a limited validity period (a few minutes). After the authorization code expires, the customer must disable and enable the skill again. Re-enabling the skill generates a new authorization code and prompts Alexa to send the Alexa.Authorization.AcceptGrant directive to your skill.
  • You must store the access and refresh tokens for a customer and include the access token in each asynchronous response or event that you send to the Alexa event gateway. Before the token expires, you must use the stored refresh token to get new access and refresh tokens from LWA. Access tokens are typically valid for 60 minutes.
  • When you migrate a skill from the Smart Home Skill API v2 to v3 message format, and you have requested permission to send events to the Alexa event gateway, Alexa has a backfill process. Alexa sends an Alexa.Authorization.AcceptGrant directive for every customer that enabled your skill. Be prepared to receive these messages and complete the authentication process. For details about skill migration, see Smart Home Skill v2-to-v3 Migration Guide.

Testing tools

The Alexa Skills Kit (ASK) has multiple tools to help you test and debug state and other events as you build your Alexa smart home skill. For details, see Debug Your Smart Home Skill.

Sample code

The following sample code demonstrates how to set up your smart home skill to send change reports to the Alexa event gateway:

Was this page helpful?

Last updated: Aug 08, 2024