Alexa 3.0

The Alexa capability interface comprises the mechanics related to state and error reporting for other capabilities.

The documentation for other capabilities will indicate whether they leverage the Alexa interface for these mechanisms.

Dependencies

A device maintaining an HTTP/2 connection that implements the Alexa 3.0 capability on its own behalf or on behalf of other connected endpoints must also implement support for Alexa.Discovery 3.0 or higher.

Capability assertion

To use the Alexa capability, it must be asserted in the capabilities list of a Discover.Response or AddOrUpdateReport event in the Alexa.Discovery interface.

The Alexa capability may be implemented by the device maintaining the HTTP/2 connection to AVS both on its own behalf as an endpoint and on behalf of other endpoints. Support for the Alexa capability must be asserted in the capabilities list for each endpoint that leverages it.

Sample Object

{
  "type": "AlexaInterface",
  "interface": "Alexa",
  "version": "3"
}

Directives

EventProcessed

AVS will send the EventProcessed directive to inform the device that an event it previously sent was successfully processed. This accommodates scenarios where synchronous responses to events are not possible and the device depends on the response for a further activity or experience.

The documentation for individual events in other capability interfaces will specify whether AVS may return an EventProcessed directive. Those events will specify an eventCorrelationToken in their header objects, which this EventProcessed directive will return.

An example of an event that AVS replies to with the EventProcessed directive is AddOrUpdateReport.

Sample Message

{
  "directive": {
    "header": {
      "namespace": "Alexa",
      "name": "EventProcessed",
      "messageId": "{{STRING}}",
      "eventCorrelationToken": "{{STRING}}"
    },
    "payload": {
    }
  }
}

Message Parameters

Parameter Description Type
directive.
  header.
    messageId
A universally unique identifier (UUID) generated to the RFC 4122 specification. string
directive.
  header.
    eventCorrelationToken
The token corresponding to the device-generated eventCorrelationToken provided in any event that requires that AVS send the EventProcessed directive in response. string

Note: The payload is an empty object.

ReportState

AVS will send the ReportState directive to instruct the device to provide the current values for all reportable state properties that are retrievable for a particular endpoint.

The device must send the StateReport event in response.

Sample Message

{
  "directive": {
    "header": {
      "namespace": "Alexa",
      "name": "ReportState",
      "payloadVersion": "3",
      "messageId": "{{STRING}}",
      "correlationToken": "{{STRING}}"
    },
    "endpoint": {
      "endpointId": "{{STRING}}"
    }
    "payload": {
    }
  }
}

Message Parameters

Parameter Description Type
directive.
  header.
    messageId
A universally unique identifier (UUID) generated to the RFC 4122 specification. string
directive.
  header.
    correlationToken
An opaque token that must be included in any events responding to this directive. string
directive.
  endpoint.
    endpointId
The identifier of the endpoint for which the reportable state properties are being queried. string

Note: The payload is an empty object.

Events

ChangeReport

The device must send the ChangeReport event on behalf of itself and any connected endpoints for all reportable state properties that can be proactively reported, whenever those states change.

A single ChangeReport event is always sent on behalf of only one endpoint, but it may report the changed states associated with more than one capability interface for that endpoint.

Individual capability interfaces define whether their reportable state properties can be included by setting the proactivelyReported field to true in their capability assertion through the Alexa.Discovery interface.

Sample Message

{
  "context": [
    // Optional: reportable state properties that did not change
  ],
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "payloadVersion": "3",
      "messageId": "{{STRING}}"
    },
    "endpoint": {
      "endpointId": "{{STRING}}"
    }
    "payload": {
      "change": {
        "cause": {
          "type": "{{STRING}}"
        }
      },
      "properties": [
        // Required: reportable state properties that changed
      ]
    }
  }
}

Message Parameters

Parameter Description Type
context A list of reportable state property objects that have not changed.

These may be included to provide Alexa with fresher and more complete information about an endpoint's state.

This list may, but is not required to, include context entries defined by other capabilities, such as AudioPlayer's PlaybackState.

Note: If a reportable state property is included in this list, it must not appear in the properties list of the payload. In other words, the same namespace and name pair may not appear in both this context list and the properties list of the payload.

Note: This context field may be represented as an object with a subordinate properties list. See alternative JSON representations for context for more information.
list
event.
  header.
    messageId
A universally unique identifier (UUID) generated to the RFC 4122 specification. string
event.
  endpoint.
    endpointId
The identifier of the endpoint on behalf of which the state properties are being reported. string
event.
  payload.
    change.
      cause.
        type
The cause of the change.

Accepted Values:
APP_INTERACTION: user interaction with an app, such as turning on a light with a third-party companion app
PHYSICAL_INTERACTION: user's physical interaction with the endpoint, such as changing the temperature on a thermostat directly
PERIODIC_POLL: detected by the HTTP/2 device's polling the endpoint on some interval
RULE_TRIGGER: triggered by a rule or routine previously configured by the user, such as lights turning on if motion is detected
VOICE_INTERACTION: user's voice request to Alexa to change the state of an endpoint, such as asking an Echo to turn on the lights
string
event.
  payload.
    properties
A list of reportable state property objects that changed for the specified cause. list

DeferredResponse

The device must send the DeferredResponse event on behalf of itself and any connected endpoints when sending a synchronous Response event is not possible.

Instead of defining events within the same namespace, some capabilities require that responses to directives leverage the centralized Response event in the Alexa capability. Because some directives take time to fully execute, the device may send the DeferredResponse event synchronously, as a promise to later send an asynchronous Response event. This allows Alexa to render an optimal user experience, rather than silence or timing out.

When the device sends the DeferredResponse event, it must later send the Response event, as soon as the directive that triggered it is finished processing.

Note: DeferredResponse is only supported for some capability interfaces. Refer to the documentation for individual interfaces to see whether DeferredResponse is supported as an alternative to responding with an immediate Response event.

Sample Message

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "payloadVersion": "3",
      "messageId": "{{STRING}}"
      "correlationToken": "{{STRING}}"
    },
    "payload": {
      "estimatedDeferralInSeconds": {{LONG}}
    }
  }
}

Message Parameters

Parameter Description Type
event.
  header.
    messageId
A universally unique identifier (UUID) generated to the RFC 4122 specification. string
event.
  header.
    correlationToken
An opaque token that corresponds to the directive to which this event is the response. string
event.
  payload.
    estimatedDeferralInSeconds
The approximate time, in seconds, that your device estimates it will take to complete execution of the directive, at which point it will send the Response event. long

ErrorResponse

The device must send the ErrorResponse event on behalf of itself and any connected endpoints when it is unable to process a directive as expected. This applies only when the directive belongs to a capability interface that defines ErrorResponse as the mechanism for reporting errors.

Sample Message

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "payloadVersion": "3",
      "messageId": "{{STRING}}",
      "correlationToken": "{{STRING}}"
    },
    "endpoint": {
      "endpointId": "{{STRING}}"
    }
    "payload": {
      "type": "{{STRING}}",
      "message": {{STRING}}",
      ...
    }
  }
}

Message Parameters

Parameter Description Type
event.
  header.
    messageId
A universally unique identifier (UUID) generated to the RFC 4122 specification. string
event.
  header.
    correlationToken
An opaque token that corresponds to the directive to which this event is the response. string
event.
  endpoint.
    endpointId
The identifier of the endpoint on behalf of which the state properties are being reported. string
event.
  payload.
    type
The type of error. All error details may be shared with the user.

Accepted Values: Those listed in error type values of the Smart Home Skills Kit documentation.
string
event.
  payload.
    message
Additional information about the error for diagnostic and troubleshooting purposes. Alexa will not share this information with the user. string
event.
  payload.
    additional fields
The error type may define additional fields in the payload. Refer to the error type values and following examples of the Smart Home Skills Kit documentation for more information. string

Response

Instead of defining events within the same namespace, some capabilities require that responses to directives leverage the centralized Response event in the Alexa interface. For such capabilities, the device must send the Response event on behalf of itself and any connected endpoints.

Note: If the device or endpoint is not able to complete acting on the directive synchronously, due to reasons such as physical processes that take time to finish or expected network latency, it may send the DeferredResponse event instead and follow up later with the Response event when the directive has been fully executed. The DeferredResponse event is only supported for some capability interfaces.

Sample Message

{
  "context": [
    // The reportable state properties affected by the directive
    // to which this event is a response.
  ],
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "{{STRING}}",
      "correlationToken": "{{STRING}}"
    },
    "endpoint": {
      "endpointId": "{{STRING}}"
    }
    "payload": {
    }
  }
}

Message Parameters

Parameter Description Type
context A list of reportable state property objects that the directive affected on the specified endpoint.

This list may, but is not required to, include context entries defined by other capabilities, such as AudioPlayer's PlaybackState, as well as other reportable state properties. These may be included to provide Alexa with fresher and more complete information about an endpoint's state.

Note: This context field may be represented as an object with a subordinate properties list. See alternative JSON representations for context for more information.
list
event.
  header.
    messageId
A universally unique identifier (UUID) generated to the RFC 4122 specification. string
event.
  header.
    correlationToken
An opaque token that corresponds to the directive to which this event is the response. string
event.
  endpoint.
    endpointId
The identifier of the endpoint on behalf of which the state properties are being reported. string

Note: The payload is an empty object.

StateReport

The device must sent the StateReport event in response to the ReportState directive to provide the current values for all reportable state properties that are retrievable for a particular endpoint.

Individual capability interfaces define whether their reportable state properties must be included by setting the retrievable field to true in their capability assertion through the Alexa.Discovery interface.

For changes to reportable state properties that can be proactively reported, the device should send the ChangeReport event instead.

Note: If an endpoint is offline or unreachable, rendering the reportable state properties unretrievable, the device can either send the ErrorResponse event or this StateReport event with cached values, if available. (The DeferredResponse event is not accepted here.) Which response to send depends on factors specific to the endpoint and circumstances in question, such as how stale the cached values are, what the nature of the challenge is in reaching the endpoint, what kind of endpoint it is, and whether it results in an expected and intuitive user experience.

Sample Message

{
  "context": [
    // All reportable state properties for all capabilities
    // where the value is retrievable from the endpoint.
  ],
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "payloadVersion": "3",
      "messageId": "{{STRING}}",
      "correlationToken": "{{STRING}}"
    },
    "endpoint": {
      "endpointId": "{{STRING}}"
    }
    "payload": {
    }
  }
}

Message Parameters

Parameter Description Type
context A list of all reportable state property objects, for each capability interface, for which the value is retrievable on the specified endpoint.

This list should not include context entries defined by other capabilities, such as AudioPlayer's PlaybackState.

Note: This context field may be represented as an object with a subordinate properties list. See alternative JSON representations for context for more information.
list
event.
  header.
    messageId
A universally unique identifier (UUID) generated to the RFC 4122 specification. string
event.
  header.
    correlationToken
An opaque token that corresponds to the ReportState directive to which this event is the response. string
event.
  endpoint.
    endpointId
The identifier of the endpoint on behalf of which the state properties are being reported. string

Note: The payload is an empty object.

Additional resources

The Alexa 3.0 capability has its origins in the Alexa Skills Kit. It is now available directly to AVS devices with an HTTP/2 connection, without requiring an AWS Lambda or maintaining a separate cloud service. The following resources provide additional context and examples: