Send Events to the Event Gateway

Usually when you respond to Alexa, you reply synchronously, which means that you send an event from your Lambda function to Alexa. In some cases you have the option, and in some cases you are required, to reply asynchronously, which means that you send a response event from your device cloud to the Alexa event gateway. For more information about the difference between synchronous, asynchronous, and deferred responses, see Alexa.Response Interface.

This documentation explains what you include in a message to the Alexa event gateway, and where you send it.

Event endpoints, Lambda functions and customer credentials

When you send a message to the Alexa event gateway, send it to the event endpoint that aligns with the geographic availability of your smart home skill. 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 picking geographic endpoints on the Build page for your skill in the developer console. 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 a skill that sends change report events 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 Europe endpoint.

In addition, if a customer moves between geographic 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.

Message contents

You communicate asynchronous messages to Alexa by sending HTTP POST messages to the Alexa event gateway. When you send a message to the Alexa event gateway, include the following:

  • 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 of the message depends on the type of message, for example discovery response, directive response, change report, or other type of message.

  • An endpoint object that contains two pieces of identifying information:

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

Event gateway success codes

The following table lists the success status codes you can receive from the Alexa event gateway.

HTTP response status code Description
202 Accepted The request is authorized and the message is a syntactically valid event. The event has been accepted for further logical validation and processing.

Event gateway error codes

When you receive an error code from the Alexa event gateway, retrieve the code and description fields from the payload to get more information about the error. Use the code field for logging only. Do not use the code field to program business logic.

The following is an example of an HTTP 400 error from the Alexa event gateway:

HTTP/1.1 400 Bad Request
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

{
  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "90c3fc62-4b2d-460c-9c8b-77251f1698a0"
  },
  "payload": {
    "code": "INVALID_REQUEST_EXCEPTION",
    "description": "The request was malformed"
  }
}

The following table lists the error status codes you can receive from the Alexa event gateway.

HTTP response status code Payload error code Description and possible solutions
400 Bad Request INVALID_REQUEST_EXCEPTION The message is invalid, possibly due to missing fields, incorrect values, or malformed JSON. Check your messages against the documentation to verify that your message contains all the required fields.
401 Unauthorized INVALID_ACCESS_TOKEN_EXCEPTION The access token is not valid because it is expired or malformed. Refresh your token and retry the request. If a user disables your skill, that also invalidates the access token. This means the user has revoked authorization, and you can stop sending change reports for them.
403 Forbidden SKILL_NEVER_ENABLED_EXCEPTION Make sure that you're sending the events to the correct regional endpoint. For example, events in North America should be sent to the North American endpoint.
403 Forbidden INSUFFICIENT_PERMISSION_EXCEPTION The token does not have the required permissions. Make sure the skill has permission to send Alexa events. See Steps for Asynchronous Message Authentication.
404 Not Found SKILL_NOT_FOUND_EXCEPTION The skill ID associated with this token could not be found. This error occurs when user's access token was generated when the skill was in different stage, such as certification. Try disabling and re-enabling the skill for this user.
413 Payload Too Large REQUEST_ENTITY_TOO_LARGE_EXCEPTION The size of the event payload is too large. The maximum number of endpoints allowed in a request is 300. Send your message with smaller payloads.
429 Too Many Requests THROTTLING_EXCEPTION The number of requests is too high. Resend the message up to three times, with at least a one-second interval between each send attempt.
500 Internal Server Error INTERNAL_SERVICE_EXCEPTION An error occurred with Alexa, and the message couldn't be processed. Resend the message up to three times, with at least a one-second interval between each send attempt. If problems persist, contact Amazon Support.
503 Service Unavailable SERVICE_UNAVAILABLE_EXCEPTION Alexa couldn't accept the message. Resend the message up to three times, with at least a one-second interval between each attempt. If the problem persists, contact Amazon Support.

Testing tools

There are multiple tools to help you test and debug state and other events as you build your Alexa Smart Home skill. For more information, see Debug Your Smart Home Skill.

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. Use the resources provided in the Alexa Smart Home GitHub repo to create unit tests and test scripts that validate these messages before you send them.