Your Alexa Dashboards Settings

Send Events to the Event Gateway

When you respond to Alexa, you have the option of responding to the Alexa event gateway. This document covers what is included in a message and where you send it.

Event endpoints, Lambda functions and customer credentials

When you send a proactive state or asynchronous event to Alexa, you should communicate with the event endpoint that aligns with the geographic availability of your smart home skill(s). Following is the list of endpoints and the regions they cover.

  • North America: https://api.amazonalexa.com/v3/events
  • Europe: https://api.eu.amazonalexa.com/v3/events
  • Far East: https://api.fe.amazonalexa.com/v3/events

You must:

  • Provide a Lambda for each geographic region where your skill requires permissions. Enable this by using the Provide geographical region endpoints option on the Configuration page for your skill in the developer portal. Provide ARNs for each region you select.
  • Obtain and store customer credentials by region, meaning if you receive an AcceptGrant request to a region-specific Lambda function, you store the credentials so that they can be accessed by the same Lambda.
  • Communicate with the endpoint in the same region as your Lambda function on behalf of customers for that region

For example, if you offer your skill that sends change notification in the US and the UK, you must configure Lambdas for both North America and Europe. An AcceptGrant request for a US customer is sent to your skill’s North America Lambda. You complete the authorization flow with LWA and store the token for that customer so it can be accessed by your skill’s North America Lambda. You send events for that customer to https://api.amazonalexa.com/v3/events. For a UK customer, the AcceptGrant is sent to the Lambda configured for Europe and you store and send events the the Europe endpoint.

In addition, if a customer changes regions, they will have to re-enable and relink their skill so you will know to change where their information is stored.

The following image shows the process of authenticating a customer and sending messages on their behalf to the Alexa event gateway.

image

Message contents

You communicate the asynchronous response, change report and state report events to Alexa by sending HTTP POST messages to the Alexa event gateway that is appropriate for your skill. For a list of endpoints, see Alexa event endpoints.

You will include:

  • An authorization header containing the bearer token that is also included in the scope property of the message.
  • A content-type header indicating the content type is JSON
  • A JSON-formatted message body. The body could contain an Response, ChangeReport or StateReport depending on the purpose of the message.
  • An endpoint object that contains two pieces of identifying information:

For message body examples, see State Reporting in a Smart Home Skill Response examples in the individual interface topics.

Following is an example of how a message to the event gateway might look:

POST /v3/events HTTP/1.1
Host: api-amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json

{
  "context": {
    "properties": [
    ]
  },
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
       },
       "endpointId" :  "endpoint-id"
    },
    "payload": {
    }
  }
}

Success response and errors

When you send a message to the Alexa event gateway, you should either receive an 202 Accepted response, which indicates the message has been accepted for processing, or an error. The following table lists the responses you could expect and their related scenarios.

HTTP Response Scenario
202 Accepted The message was received and has been accepted for processing. This does not imply that the message is well formed or passes any kind of validation. To ensure your messages can be processed, validate your message to the gateway using the Validation Schema.
403 Forbidden The skill has been disabled and authorization for that customer has been revoked.
401 Unauthorized The skill is enabled, but the authentication token has expired.
400 Bad Request The message contains other invalid identifying information such as a invalid endpoint Id or correlation token.

Event responsiveness

When you receive a directive, you can send a synchronous response or a DeferredResponse indicating you received the directive, and later follow up with an asynchronous event to the Alexa endpoint. In either case, there is a hard limit of 8 seconds before Alexa times out.

Known exceptions to the 8 second limit are:

Capability Interface Notes
LockController With slower locks, specify the expected deferral of the Response with the estimatedDeferralInSeconds in the DeferredResponse.

Testing messages

Because events sent to the Alexa event gateway can affect the display in the Alexa app, you must make sure events you send Alexa are well formatted and contain the correct credentials. If your message is malformed, it can be rejected from the endpoint. Use the resources provided in the Alexa Smart Home GitHub repo to create unit tests and test scripts that validate these messages prior to sending them.