AVS Envelope and Capability Versioning

From time to time, new Alexa functionality becomes available that depends on changes to the API contract between devices and AVS.

Some aspects of the API contract are global. They pertain to the overall JSON format of all messages and general mechanics across all capability interfaces. This is called the envelope, and changes are captured in what is called the "envelope version" or "AVS version". The current version is v20160207.

Other aspects of the API contract are reflected in the creation of new or changes to existing capability interfaces. These changes do not impact the functionality of other interfaces and are narrower in scope, and they are captured in a major.minor interface version.

Envelope Version

The envelope primarily refers to the JSON format of AVS messages. It defines the existence of events and directives, their general structure, and the possible fields in header objects.

A device asserts support for a particular envelope version when it establishes its HTTP/2 connection, registering for the /<version>/directives downchannel and sending events on the /<version>/events URI path. The current AVS envelope version is v20160207.

Events

{
  "context": [
    // context entries as required/allowed by the
    // capability interface defining the event
  ],
  "event": {
    "header": {
      "namespace": "{{STRING}}",
      "instance": "{{STRING}},
      "name": "{{STRING}}",
      "payloadVersion": "{{STRING}}",
      "messageId": "{{STRING}}",
      "correlationToken": "{{STRING}}",
      "eventCorrelationToken: "{{STRING}}",
      "dialogRequestId": "{{STRING}}"
    },
    "endpoint": {
      "endpointId": "{{STRING}}"
    }
    "payload": {
      // payload as defined by the capability interface
    }
  }
}

Message Parameters

Parameter Description Type
context A list of context entries that must or may be sent with the event, as defined by the capability interface to which the event belongs. These entries may be generic context entries or reportable state properties.

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.
    namespace
The capability interface to which the event belongs. string
event.
  header.
    instance
The named primitive instance, if namespace is a capability primitive. string
event.
  header.
    name
The name of the event, unique within the namespace, which defines the payload, certain header field values, and which context entries may or must be attached. string
event.
  header.
    payloadVersion
The interface version of the namespace.

Whether this field is required is defined by the capability interface.
string
event.
  header.
    messageId
A universally unique identifier (UUID) generated to the RFC 4122 specification. string
event.
  header.
    correlationToken
An opaque token that informs Alexa that the event is a response to a previously sent directive. The value will be the same as that directive.

Whether this field is required is defined by the event.
string
event.
  header.
    eventCorrelationToken
A universally unique identifier (UUID) generated to the RFC 4122 specification that allows the device to correlate the event with any directives Alexa sends in response.

Whether this field is required is defined by the event.
string
event.
  header.
    dialogRequestId
A universally unique identifier (UUID) generated to the RFC 4122 specification that allows the device to correlate the event with any directives Alexa sends in response.
Whether this field is required is defined by the event.
string
event.
  endpoint.
    endpointId
The identifier of the endpoint on behalf of which the event is being sent. This identifier is the same as device-provided endpointId reported in Alexa.Discovery.

Whether the event is part of a capability interface that can be implemented by the device on behalf of a connected endpoint is defined by the interface. If the event is being sent on behalf of a connected endpoint, the endpoint object is required.

If the endpoint object is omitted, Alexa will interpret the event as being sent on behalf of the device itself.
string
event.
  payload
The substantive content of the event. The structure is defined by the combination of namespace, interface version, and name. object

Directives

{
  "directive": {
    "header": {
      "namespace": "{{STRING}}",
      "instance": "{{STRING}},
      "name": "{{STRING}}",
      "payloadVersion": "{{STRING}}",
      "messageId": "{{STRING}}",
      "correlationToken": "{{STRING}}",
      "eventCorrelationToken: "{{STRING}}",
      "dialogRequestId": "{{STRING}}"
    },
    "endpoint": {
      "endpointId": "{{STRING}}"
    }
    "payload": {
      // payload as defined by the capability interface
    }
  }
}

Message Parameters

Parameter Description Type
directive.
  header.
    namespace
The capability interface to which the directive belongs. string
directive.
  header.
    instance
The named primitive instance, if namespace is a capability primitive. string
directive.
  header.
    name
The name of the directive, unique within the namespace, which defines the payload and certain header field values. string
directive.
  header.
    payloadVersion
The interface version of the namespace.

If the field is omitted, the device must interpret the message according to the version it asserted in Alexa.Discovery.
string
directive.
  header.
    messageId
A universally unique identifier (UUID) generated to the RFC 4122 specification. string
event.
  header.
    correlationToken
An opaque token identifying directives generated by Alexa that may expect an event response from the device. The device must return the value verbatim in the correlationToken field of any events that are responses to the directive.

Whether this field will be sent is defined by the directive.
string
directive.
  header.
    eventCorrelationToken
An opaque token returned by Alexa when the directive is a response to an event initiated by the device. The value will be the same as the eventCorrelationToken in the corresponding event.

Whether this field will be sent is defined by the directive.
string
directive.
  header.
    dialogRequestId
An opaque token returned by Alexa when the directive is a response to an event initiated by the device. The value will be the same as the dialogRequestId in the corresponding event.

Whether this field will be sent is defined by the directive.
string
directive.
  endpoint.
    endpointId
The identifier of the endpoint that this directive is for. This identifier is the same as device-provided endpointId reported in Alexa.Discovery.

Whether the directive is part of a capability interface that can be implemented by the device on behalf of a connected endpoint is defined by the interface. If the directive is being sent for a connected endpoint, the endpoint object will be populated.

If the endpoint object is omitted, the device must interpret the directive as being for itself, not any connected endpoint.
string
directive.
  payload
The substantive content of the directive. The structure is defined by the combination of namespace, interface version, and name. object

Interface Version

Each capability interface has its own major.minor version to accommodate granular updates to functionality that enable new end user experiences and operational enhancements. The capability version controls the following aspects:

  • the event and directive messages in the interface
  • any context entries, including both generic context and reportable state properties
  • state reporting mechanics, including whether and which context is required to be attached to any of the interface's events
  • the values of fields in the header object on a per-message basis, as well as the conditions under which those fields are required
  • the structure and contents of the payload object for each message
  • how support for the capability is asserted, including any configuration options
  • settings and settings mechanics

The capability interface version is reflected in two places:

  • the version field of the capability assertion object, reported in Alexa.Discovery
  • the optional payloadVersion field included in the header object of events and directives

Major Version

When backward-incompatible changes are introduced, the major number for an interface version is increased. Here are a few examples of what would result in a major version change:

  • previously defined directives, events, or context entries are removed from an interface
  • the data type for an existing parameter is changed
  • parameters are removed from the message payload of an existing directive or event

For example, the SpeechRecognizer interface version was incremented from 1.0 to 2.0 when the initiator field's type was changed from a string to an object in the ExpectSpeech directive.

Minor Version

For backward-compatible changes, the minor number for an interface version is increased. A minor version change generally occurs when:

  • new directives, events, or context entries are added to an interface
  • parameters are added to the message payload of a directive, event, or generic context entry

For example, the Alerts interface version was incremented from 1.0 to 1.1 to support named timers and reminders. This change introduced new payload parameters to the SetAlert directive for enhanced functionality.