Response Events
When you handle an Alexa directive successfully, respond with a response event. The most generic response event is Alexa.Response
. Some directives have more specific response events, for example, an Add
directive might have an AddResponse
response event. Check the documentation for your specific interface and directive to determine the correct response event to use.
If you can't handle a directive successfully, respond with an Alexa.ErrorResponse event instead.
Types of responses
When you handle an Alexa directive successfully, respond with a response event. You can respond in one of the following ways:
- Synchronously, which means that you send a response event from your Lambda function to Alexa.
- Asynchronously, which means that you send a response event from your device cloud to the Alexa event gateway.
Usually, Alexa waits eight seconds for your response before timing out. For devices that make physical changes that take longer, such as a lock, you might have to send a deferred response before you send your regular response. For details, see deferred response.
In the context object of your response, include the values of all the properties of the endpoint that changed and the time of the change. You also include the values of properties that didn't change, to give Alexa the complete current state of the endpoint.
All response messages should include a correlation token.
Synchronous response
Check the documentation for your specific interface to determine the correct response properties to the Alexa directive.
Synchronous response example
The following example shows a standard synchronous response. In this example, the endpoint supports the Alexa.PowerController
interface and the TurnOn
directive.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint ID"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
Asynchronous response
When you respond asynchronously, you send an HTTP request to the Alexa event gateway. In the request body, you include the response event. Your response must include the access token that authenticates your skill customer to Alexa.
Asynchronous response example
The following example shows an asynchronous response. In this example, the endpoint supports the Alexa.ColorTemperatureController
interface.
POST /v3/events HTTP/1.1
Host: api-amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an 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": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
Asynchronous response event properties
Check the documentation for your specific interface and directive to determine the correct response properties.
Alexa response to the asynchronous response event
On success, Alexa sends 202 Accepted
to indicate that the event was accepted for further logical validation and processing. If the event isn't accepted, Alexa sends the appropriate HTTP status code.
Response body parameters
The 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 |
---|---|---|
|
— |
Request is authorized and the message is a syntactically valid event. The event was accepted for further logical validation and processing. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
Number of requests is too high. Resend the message up to three times, with at least a one-second interval between each send attempt. |
|
|
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. |
|
|
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."
}
}
DeferredResponse
Usually, Alexa waits for your response for eight seconds before timing out. Exceptions are noted in the documentation for individual interfaces. If your response takes more than eight seconds, first send a synchronous DeferredResponse
event, and then follow it with a Response
event, either synchronous or asynchronous.
DeferredResponse
is only supported for some interfaces, for example Alexa.LockController. Check the documentation for your specific interface to determine if DeferredResponse
is supported.
Because you always send a DeferredResponse
synchronously, don't include a scope.
DeferredResponse event payload
Field | Description | Type | Required |
---|---|---|---|
estimatedDeferralInSeconds |
The approximate time before you send your second response, in seconds. | Integer | No |
DeferredResponse example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "DeferredResponse",
"messageId": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an opaque correlation token that matches the request",
"payloadVersion": "3"
},
"payload": {
"estimatedDeferralInSeconds": 7
}
}
}