Your Alexa Dashboards Settings

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.

Message Structure
Click to enlarge

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:

  • POST for all events sent to the AVS using the events path
  • GET for 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 +

Resources