Structure an HTTP/2 Request for AVS
AVS API Version:
v20160207
Once a connection with the Alexa Voice Service (AVS) is established, your client will communicate with the Alexa using HTTP/2 encoded multipart messages. The events sent from your client, as well as directives sent by Alexa, specify actions that the server or client should take. The following diagram illustrates a Recognize event sent to AVS. The multipart message is composed of two parts. The first, a JSON-formatted event, the second, captured audio from a product's microphone.
For information on creating and maintaining a connection, see Managing an HTTP/2 Connection.
HTTP/2 Message Headers
Each call to AVS requires the following headers:
:method = {{verb}}
:scheme = https
:path = /{{API version}}/{{events or directives}}
authorization = Bearer {{access_token}}
content-type = multipart/form-data; boundary={{boundary_term}}
Method
AVS supports the following methods:
POSTfor all events sent to the AVS using the events pathGETfor establishing the downchannel using the directives path
Scheme
The scheme for accessing the AVS API is https.
Paths
All events use the following path:
:path = /v20160207/events
All directives use the following path:
:path = /v20160207/directives
Authorization
When a user authorizes your product to access Alexa on their behalf, Login with Amazon returns an access_token which is then used to make calls to AVS. The access_token must be included in the header of each request.
authorization = Bearer {{access_token}}
Content Type
Content-Type describes the data contained in the body. This allows the AVS to appropriately process the request. The boundary term separates different parts of a multipart message. In the case of Alexa, JSON and binary audio.
Content-Type should always be multipart/form-data. You are free to determine your own boundary term. The only requirements are that the boundary term is used consistently and that the boundary doesn't exist in the data.
content-type = multipart/form-data; boundary={{boundary_term}}
HTTP/2 Multipart Messages
AVS expects HTTP/2 encoded multipart messages. Multipart messages are composed of one or more JSON-formatted directives/events and their associated binary audio attachments (if required). In this section, we'll review the structure of a multipart message sent to AVS.
JSON Headers
The following headers are required for the JSON part of each multipart request:
Content-Disposition: form-data; name="metadata" Content-Type: application/json; charset=UTF-8
JSON Content
All JSON-formatted events sent to AVS are formatted as follows:
{
"event":{
"header": {
"namespace": "{{STRING}}",
"name": "{{STRING}}",
"messageId": "{{STRING}}",
},
"payload": {
}
}
}
Each event has a unique header and payload. In the header, namespace and name identify the interface and the event, and messageId is a unique identifier your client must send with each request. For additional information and samples, see API Overview.
Binary Audio Headers
The following headers are required for the binary audio attachment of each multipart request:
Content-Disposition: form-data; name="audio" Content-Type: application/octet-stream
Binary Audio Content
This part of the multipart message is binary audio. The only event that requires an audio attachment is a Recognize event. For detailed information, see SpeechRecognizer Interface.
HTTP/2 Responses
AVS will send two types of responses to your client. The first type, like requests, are multipart messages composed of one or more JSON-formatted directives and their associated binary audio attachments (if required). The second type are exceptions. Exceptions are not multipart messages and are returned to your client when an error occurs. Each exception will include an error code and a description.
For additional information, see Exceptions.
Examples
Example 1:
This example shows a Recognize event that receives one Speak directive as a response.
Click here to expand +
Example 2:
This example shows a Recognize event that receives one Speak directive and one Listen directive as a response.
Click here to expand +
