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:

Discovery events, such as AddOrUpdateReport and DeleteReport.
Asynchronous responses and error responses.
Alexa.ChangeReport event. To send change reports, you configure properties that your smart home add-on proactively reports during discovery. For details, see Understand State and Change Reporting.
Events defined by a specific capability interface.
For details, see the documentation for each interface that you support in your add-on.

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 add-on 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 an add-on 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 add-on’s North America Lambda function. You store the access tokens for that customer so that your add-on’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 add-on. Then, your add-on 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 add-on 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

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.

{
    "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 add-on might receive from the Alexa event gateway. If you receive an error, the response body contains the error code and description. 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 not valid 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 expired, malformed, or not valid. Refresh your token and retry the request. If a user disables your add-on, that also invalidates the access token.
`403 Forbidden`	`SKILL_DISABLED_EXCEPTION`	The customer disabled your add-on. Stop sending events for the customer and delete any stored tokens in your system.
`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. Otherwise, the customer never enabled your add-on.
`403 Forbidden`	`INSUFFICIENT_PERMISSION_EXCEPTION`	Token doesn’t have the required permissions. Make sure that the add-on 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 directed identifier that’s not valid. 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 add-on was in different stage, such as certification. Try disabling and re-enabling the add-on 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 error response body

The following example shows an error response.

HTTP/1.1 401 Unauthorized
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

{
  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "Unique version 4 UUID"
  },
  "payload": {
      "code": "INVALID_ACCESS_TOKEN_EXCEPTION",
      "description": "The access token is invalid, expired, or malformed."
  }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Asynchronous event types

Gateway endpoints

Asynchronous event definition

API endpoint

Authentication

Request

Request header example

Request header parameters

Request body example

Request body parameters

Response

Response body parameters

HTTP status codes

Example error response body

​Asynchronous event types

​Gateway endpoints

​Asynchronous event definition

​API endpoint

​Authentication

​Request

​Request header example

​Request header parameters

​Request body example

​Request body parameters

​Response

​Response body parameters

​HTTP status codes

Example error response body

Asynchronous event types

Gateway endpoints

Asynchronous event definition

API endpoint

Authentication

Request

Request header example

Request header parameters

Request body example

Request body parameters

Response

Response body parameters

HTTP status codes