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:

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.

Copied to clipboard.

{
  "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.

Copied to clipboard.

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

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 7
    }
  }
}