About AVS Versions

From time to time, the Alexa Voice Service (AVS) releases updates with new features and functionality. To track the changes associated with these updates, AVS uses two different versioning systems:

  • Envelope version – The envelope version refers to the overall version of AVS and increments for global changes that apply to the overall JSON format of all messages and general mechanics across all AVS interfaces.
  • Interface version – The interface version tracks updates within an individual AVS interface. These changes apply solely to the given interface and don't impact the functionality of other interfaces. Interface versions have a "major.minor" format.

Envelope version

The envelope refers to the JSON format of AVS messages. The envelope defines the existence of events and directives, their structures, and the 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 to send with the event, as defined by the interface associated with the event. These entries might be either generic context entries or reportable state properties.

Note: An object with a subordinate properties list can represent the context field. For more details, see alternative JSON representations for context. 		list
event.
  header.
    namespace		 The capability interface to which the event belongs. string
event.
  header.
    instance		 The named controller instance, if namespace is a generic controller. string
event.
  header.
    name		 The name of the event, unique within the namespace, which defines the payload, certain header field values, and the context entries to attach. string
event.
  header.
    payloadVersion		 The interface version of the namespace.

The interface determines whether to require this field. 		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 is the same as the directive.

The event determines whether to require this field. 		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.

The event determines whether to require this field. 		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.
The event determines whether to require this field. 		string
event.
  endpoint.
    endpointId		 The identifier of the endpoint associated with the event. This identifier is the same as device-provided endpointId reported in Alexa.Discovery.

The interface defines whether the device can implement the event as part of an interface on behalf of a connected endpoint. The interface requires an endpoint object for events associated with a connected endpoint.

If the event omits the endpoint, Alexa interprets the event as sent on behalf of the device itself. 		string
event.
  payload		 The substantive content of the event. A combination of namespace, interface version, and name define the structure. 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 controller instance, if namespace is a generic controller. 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 directive omitted this field, 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
directive.
  header.
    correlationToken		 An opaque token identifying directives generated by Alexa that might 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.

The directive determines whether to send this field. 		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 is the same as the eventCorrelationToken in the corresponding event.

The directive determines whether to send this field. 		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 is the same as the dialogRequestId in the corresponding event.

The directive determines whether to send this field. 		string
directive.
  endpoint.
    endpointId		 The identifier of the endpoint associated with the directive. This identifier is the same as device-provided endpointId reported in Alexa.Discovery.

The interface defines whether the device can implement the directive as part of a capability interface on behalf of a connected endpoint. If AVS sends the directive for a connected endpoint, the endpoint object becomes populated.

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

Interface version

Interface versioning uses a "major.minor" convention to track updates to functionality that enable new user experiences and operational enhancements, including the following examples:

  • Event and directive messages in the interface.
  • Any context entries, including both generic context and reportable state properties.
  • State reporting mechanics, including any context to attach to any interface events.
  • Field values in header object messages and the rules specifying when a message requires a given field.
  • Structure and contents of the payload object for each message
  • How to assert support for a capability, including any configuration options.
  • Settings and setting mechanics.

Two fields specify the interface version:

  • 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 interface versions

When an update introduces backward-incompatible changes, the major number for an interface version increases. Updates that result in a major version change include the following scenarios:

  • An update removes existing directives, events, or context entries.
  • The data type for an existing parameter changes.
  • An update removes parameters from the message payload of an existing directive or event.

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

Minor interface versions

For backward-compatible changes, the minor number for an interface version increases. Updates that result in a minor version change include the following scenarios:

  • An update adds new directives, events, or context entries to an interface.
  • An update adds new parameters to the message payload of a directive, event, or generic context entry.

For example, the Alerts interface version increased 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.

Last updated: Dec 08, 2020