Alexa.Response Interface 3

When you handle an Alexa directive successfully, send a response event. A successful response confirms that the endpoint completed the requested action. For example, the light turned on, the temperature changed, or the lock engaged. The most generic response event is Alexa.Response. Some directives have more specific response events. For example, the Alexa.ReportState directive requires an Alexa.StateReport response, but the Alexa.PowerController directives use Alexa.Response. To determine the correct response to use, check the documentation for your specific interface and directive. If you can’t handle a directive successfully, send an Alexa.ErrorResponse event instead. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Types of responses

The Alexa interface supports three types of responses:

Synchronous – You respond to the directive from your Lambda function.
Asynchronous – You send a response event from your device cloud to the Alexa event gateway.
Deferred – For devices that make physical changes, such as a lock, that take longer than eight seconds, send a deferred response before you send your regular synchronous or asynchronous response.

Synchronous response

Specify the following information in a synchronous response.

Identify the endpoint for the response in the endpoint object.
Include the correlationToken set to the value from the directive request.
Include response properties in the payload object.
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. Also, include the values of properties that didn’t change, to give Alexa the complete current state of the endpoint.

Synchronous response example

The following example shows a standard synchronous response. In this example, the endpoint supports the Alexa.PowerController interface and responds to the TurnOn 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": {
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

Synchronous response properties

Property	Description	Type	Required
`event`	Defines header and endpoint information.	`Event` object	Yes
`event.header`	Identifies the response and interface. To enable Alexa to correlate the response with the directive, you must set the `header.correlationToken` to the `header.correlationToken` value from the directive request.	`Header` object	Yes
`event.endpointId`	Identifies the endpoint.	String	Yes
`event.payload`	Identifies the properties required in the response. The payload varies for each interface directive and response. Review the documentation for your specific interface to determine the correct response properties. If the response doesn’t include any properties, set `payload` to an empty object.	Object	Yes
`context`	Include to return the current state of all the retrievable properties, including the properties that didn’t change.	`Context` object	No

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 add-on customer to Alexa. Specify the following information in an asynchronous response:

Identify the endpoint for the report in the endpoint object.
Include the correlationToken set to the value from the directive request.
Include the access token in the endpoint.scope object.
Include response properties in the payload object.
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. Also, include the values of properties that didn’t change, to give Alexa the complete current state of the endpoint.

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": "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": "2017-02-03T08:00:00.10Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

Asynchronous response properties

Property	Description	Type	Required
`event`	Defines header and endpoint information.	`Event` object	Yes
`event.header`	Identifies the response and interface. To enable Alexa to correlate the response with the directive, you must set the `header.correlationToken` to the `header.correlationToken` value from the directive request.	`Header` object	Yes
`event.endpointId`	Identifies the endpoint.	String	Yes
`event.endpoint.scope`	Access token for the Alexa event gateway. For details, see Request Access Tokens.	`Scope` object	Yes
`event.payload`	Identifies the properties required in the response. The payload varies for each interface directive and response. Check the documentation for your specific interface to determine the correct response properties. If the response doesn’t include any properties, set `payload` to an empty object.	Object	Yes
`context`	Include to return the current state of all the retrievable properties, including the properties that didn’t change.	`Context` object	No

When you send an asynchronous Alexa.Response to the gateway, Alexa sends an HTTP status code to indicate success or failure.

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

Deferred response

Alexa waits for your response for eight seconds before timing out. Some interfaces require a shorter response. Some interfaces take longer, such as devices that make physical changes. If your response takes more than eight seconds, first send a synchronous Alexa.DeferredResponse event, and then follow it with an Alexa.Response, either synchronous or asynchronous. Alexa supports Alexa.DeferredResponse for the following interfaces:

Alexa.LockController
Alexa.WakeOnLANController
Alexa.ReportState for properties defined in these interfaces

Because you always send an Alexa.DeferredResponse synchronously, don’t include an endpoint.scope.

Deferred response example

The following example shows a deferred response that estimates the full Alexa.Response will follow within seven seconds.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "estimatedDeferralInSeconds": 7
    }
  }
}

Deferred response properties

Property	Description	Type	Required
`event`	Defines header and endpoint information.	`Event` object	Yes
`event.header`	Identifies the response and interface. To enable Alexa to correlate the response with the directive, you must set the `header.correlationToken` to the `header.correlationToken` value from the directive request.	`Header` object	Yes
`event.endpointId`	Identifies the endpoint.	String	Yes
`event.payload`	Identifies the deferred response properties.	Object	Yes
`event.payload.estimatedDeferralInSeconds`	The approximate time before you send your second response, in seconds.	Integer	No

Alexa errors

Errors can occur on the Alexa side after you send a response. Alexa might timeout waiting for the response or encounter errors when processing the response payload. These errors prevent completion of the user’s request. Alexa errors include the following exceptions:

SKILL_RESPONSE_TIMEOUT_EXCEPTION – Exception thrown when an add-on times out on an Alexa request to the add-on.
INVALID_SKILL_RESPONSE_EXCEPTION – Exception thrown when Alexa receives a response from the add-on that isn’t valid.
INVALID_ACCESS_TOKEN_EXCEPTION – Exception thrown by the Alexa event gateway when an event from your add-on includes an access token that’s expired, malformed, or not valid, or the token was missing. Retry the request one time.
SKILL_DISABLED_EXCEPTION – Exception thrown by the Alexa event gateway when the customer disabled your add-on and revoked authorization. You must stop sending events for this customer and delete any stored tokens for the customer in your system.
SKILL_NEVER_ENABLED_EXCEPTION – Exception thrown by the Alexa event gateway when the customer never enabled the skill, or you sent the event to the wrong regional endpoint. Do not retry the request.

You can view Alexa errors on the Capability Directives page in the Analytics tab of the Alexa developer console. For more details, see Error metrics.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Types of responses

Synchronous response

Synchronous response example

Synchronous response properties

Asynchronous response

Asynchronous response example

Asynchronous response properties

HTTP status codes

Example error response body

Deferred response

Deferred response example

Deferred response properties

Alexa errors

​Types of responses

​Synchronous response

​Synchronous response example

​Synchronous response properties

​Asynchronous response

​Asynchronous response example

​Asynchronous response properties

​HTTP status codes

Example error response body

​Deferred response

​Deferred response example

​Deferred response properties

​Alexa errors

​Related topics

Types of responses

Synchronous response

Synchronous response example

Synchronous response properties

Asynchronous response

Asynchronous response example

Asynchronous response properties

HTTP status codes

Deferred response

Deferred response example

Deferred response properties

Alexa errors

Related topics