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.
Response Overview
When you handle an Alexa directive successfully, respond with a response event. You can respond in one of two 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.
In most cases, Alexa waits 8 seconds for your response before timing out. For devices that make physical changes slowly, such as a lock, you might have to send a deferred response before you send your regular response. For more information, see deferred response.
In the context object of your response event, include the values of all the properties of the endpoint that changed. You can 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
Synchronous Response example
The following example shows a standard synchronous response. In this example, the endpoint supports the Alexa.PowerController
interface.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"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 to the Alexa event gateway, your response must include a scope that authenticates your skill user 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": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ColorTemperatureController",
"name": "colorTemperatureInKelvin",
"value": 5500,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
DeferredResponse
In most cases, Alexa waits for your response for 8 seconds before timing out. Exceptions are noted in the documentation for individual interfaces. If your response will take more than 8 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, do not include a scope.
DeferredResponse event payload details
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": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"payload": {
"estimatedDeferralInSeconds": 7
}
}
}