Send Events

After you obtain and store the access tokens for a customer, you can send proactive events and asynchronous responses to previous directives. You send these events as HTTP messages to the Alexa event gateway endpoint in the appropriate region.

Asynchronous event types

The structure of asynchronous responses and events is the same as for a synchronous message, but you send the event to the Alexa event gateway.

You send the following events to the event gateway:

Gateway endpoints

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 or video skill. The following list shows the Alexa regions and associated endpoints.

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

For example, if you offer a skill that sends change report events in the US and the UK, you must deploy Amazon Web Services (AWS) Lambda functions for both the North American and European regions. For a US customer, Alexa sends directives to your skill's North America Lambda function. You store the access tokens for that customer so that your skill's North America Lambda function can access it. You send events for that customer to the North American endpoint. For a UK customer, Alexa sends directives to the Lambda function configured for Europe and you store and send events to the European endpoint. For details about AWS Lambda endpoints, see Deploy your Lambda function to multiple regions.

In addition, if a customer moves between geographic regions, they have to re-enable and relink their skill. Then, your skill can change storage location of the associated customer information.

Asynchronous event definition

You communicate asynchronous responses and events to Alexa by sending an HTTP POST message to the Alexa event gateway.

API endpoint

Set the endpoint to the gateway endpoint in the region where the customer is located.

Authentication

To authenticate the skill with the Alexa gateway, use the bearer token authentication in the HTTP header. Include the stored access token for the customer. Make sure that you refresh access tokens before they expire.

Request

Include the access token in the request header and in the body of the message.

Request header example

Copied to clipboard.

POST /v3/events HTTP/1.1
Host: {gateway-endpoint}
Authorization: Bearer {access-token-from-Amazon}
Content-Type: application/json

Request header parameters

Parameter Description Type Required

gateway-endpoint

Set to the gateway endpoint in the region where the customer is located.

String

Yes

access-token-from-Amazon

Access token for the customer.
For details about the process to obtain access tokens for a customer, see Request Access to the Alexa Event Gateway.

String

Yes

Request body example

The following example shows an asynchronous response to a SetColorTemperature directive.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-Amazon"
            },
            "endpointId": "Endpoint id"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
            "namespace": "Alexa.ColorTemperatureController",
            "name": "colorTemperatureInKelvin",
            "value": 5500,
            "timeOfSample": "2022-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
        }]
    }
}

Request body parameters

For the definition of the request body, see the documentation for the specific event type. In the endpoint object include the scope property with type = BearerToken and token set to the access_token that you received from LWA.

Response

On success, Alexa sends 202 Accepted to indicate that the event was accepted for further logical validation and processing. If the request isn't accepted, Alexa sends the appropriate HTTP status code. For example, if you send a request with an expired token, Alexa sends an HTTP 401 Unauthorized response.

Response body parameters

This response has no body.

HTTP status codes

The following table shows the HTTP status code values that your skill might receive from the Alexa event gateway. If you receive an error, the payload object contains a code and description field. Use these fields for logging only.

Status Payload code Description

202 Accepted

—

Request is authorized and the message is a syntactically valid event. The gateway accepted the event for further logical validation and processing.

400 Bad Request

INVALID_REQUEST_EXCEPTION

Message is invalid 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

Message didn't include the authorization token or the token is invalid, expired, or malformed. Refresh your token and retry the request. If a user disables your skill, that also invalidates the access token. Here, the user revoked authorization, and you can stop sending change reports for them.

403 Forbidden

SKILL_NEVER_ENABLED_EXCEPTION

You're not allowed access to the event gateway. Make sure that you're sending the events to the correct regional endpoint. For example, send events in North America to the North American endpoint.

403 Forbidden

INSUFFICIENT_PERMISSION_EXCEPTION

Token doesn't have the required permissions. Make sure that the skill has permission to send Alexa events. For details, see Request Access to the Alexa Event Gateway.

404 Not Found

ACCOUNT_NOT_FOUND_EXCEPTION

Account record associated with this directed identifier doesn't exist or has expired. This error can occur if the event was sent too late or with an invalid directed identifier. Verify that the directed identifier and authorization code are correct.

404 Not Found

SKILL_NOT_FOUND_EXCEPTION

Skill ID associated with this token wasn't 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

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

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

Error occurred with Alexa, and the message wasn't 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.

Example 401 Unauthorized response body

The following example shows an error response.

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_ACCESS_TOKEN_EXCEPTION",
      "description": "The access token is invalid, expired, or malformed."
  }
}
Was this page helpful?

Last updated: Nov 22, 2023