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 theheader
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