Alexa.Response Interface

When you handle an Alexa directive successfully, respond with a response event. The most generic response event is Alexa.Response. Some directives might have specific response events. For example, an Add directive might have an AddResponse response event. Check the documentation for your specific directive to determine the correct response event to use.

Response

If a directive is successfully handled, you should respond with an Response event. A Response can be sent from a Lambda function to Alexa or from your device cloud to the Alexa event gateway. When you send a response event you must report the value of affected properties in the context of the message, but you can include any and all reportable properties in the context.

In most cases Alexa waits 8 seconds before timing out whether the response is synchronous or asynchronous. Exceptions are noted in individual interfaces. For example, Alexa will wait longer for an asynchronous response from an endpoint that implements the [LockController][alexa-lockcontroller] interface.

If you are responding asynchronously to the event gateway, the Response must include a scope that authenticates the customer to Alexa. When you respond synchronously or asynchronously, the message should include a correlation token.

Standard Response example

The following is the standard response format.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message_id>",
      "payloadVersion": "1"
    },
    "payload": { }
  }
}

Synchronous Response example

The following example shows a synchronous response for a endpoint that supports tunable white light.

{
    "context": {
        "properties": [ {
            "namespace": "Alexa.ColorTemperatureController",
            "name": "colorTemperatureInKelvin",
            "value": 7500,
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
        } ]
    },
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "payloadVersion": "3",
            "messageId": "abc-123-def-456",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "endpointId": "appliance-001"
        },
        "payload": {}
    }
}

Asynchronous Response example

The following example shows a asynchronous response for a endpoint that supports tunable white light.


POST /v3/events HTTP/1.1
Host: api-amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json

{
    "context": {
        "properties": [ {
            "namespace": "Alexa.ColorTemperatureController",
            "name": "colorTemperatureInKelvin",
            "value": 7500,
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
        } ]
    },
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "payloadVersion": "3",
            "messageId": "abc-123-def-456",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "scope": {
              "type": "BearerToken",
              "token": "access-token-from-Amazon"
            },
            "endpointId": "appliance-001"
        },
        "payload": {}
    }
}

DeferredResponse

Use a DeferredResponse to respond synchronously to a directive that you plan to later send a delayed or asynchronous response. After you send a DeferredResponse, you should later send a Response event.

Because you always send a DeferredResponse synchronously, it does not include a scope.

Example DeferredResponse


{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 7
    }
  }
}

Payload details

Field Description Type Required
estimatedDeferralInSeconds Optional. An integer that indicates an approximate time, in seconds, before the asynchronous response is sent. integer no