HTTP/2 Message Syntax Reference

After establishing a connection with the Alexa Voice Service (AVS), your device communicates with AVS through HTTP/2 encoded multipart messages. Refer to the following information to help you structure your HTTP/2 requests for AVS.

HTTP/2 message structure

The following diagram illustrates an example Recognize event message sent to AVS. The multipart message has two parts:

JSON-formatted event
Captured audio from the device microphone

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

Methods

AVS supports the following methods:

POST for all events sent to the AVS with the events path
GET for establishing the downchannel with the directives path

Scheme

The scheme for accessing the AVS APIs 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. Then, Alexa uses the access_token to make calls to AVS. Include the access_token in the header of each request.

authorization = Bearer {{access_token}}

Content-Type

The Content-Type parameter describes the data contained in the message body. This value helps AVS to process the request correctly. The boundary term separates different parts of a multipart message, such as JSON and binary audio.

Content-Type should always be multipart/form-data. You can determine your own boundary term. Use the boundary term consistently, and make sure that the boundary doesn't exist in the data.

content-type = multipart/form-data; boundary={{boundary_term}}

HTTP/2 multipart messages

AVS is designed to receive HTTP/2 encoded multipart messages. Multipart messages contain one or more JSON-formatted directives/events and any required associated binary audio attachments. This section reviews the structure of a multipart message sent to AVS.

JSON headers

Include the following required headers 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 use the following formatting.

{
    "event":{
        "header": {
            "namespace": "{{STRING}}",
            "name": "{{STRING}}",
            "messageId": "{{STRING}}",
        },
        "payload": {
        }
    }
}

Each event has a unique header and payload. In the header, the namespace and name identify the interface and the event, and messageId is a unique identifier your device must send with each request. For more details and samples, see API Overview.

Binary audio headers

Include the following required headers 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 details, see SpeechRecognizer Interface.

HTTP/2 responses

AVS sends two types of responses to your device. 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 aren't multipart messages and are returned to your device when an error occurs. Each exception includes an error code and a description.

For more details, see Exceptions.

Examples

Example 1:
The following example shows a Recognize event that receives one Speak directive as a response.

Expand+

Request

// Note: HTTP2 is a binary protocol and the payload is not human-readable. This is for illustrative purposes only.

:method = POST
:scheme = https
:path = /v20160207/events
authorization = Bearer foo-bar
content-type = multipart/form-data; boundary=this-is-a-boundary

--this-is-a-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json; charset=UTF-8

{
    "context": [
        {
            "header": {
                "namespace": "AudioPlayer",
                "name": "PlaybackState"
            },
            "payload": {
                "token": "abcd1234",
                "offsetInMilliseconds": 7000,
                "playerActivity": "PLAYING"
            }
        },
        {
            "header": {
                "namespace": "Alerts",
                "name": "AlertsState"
            },
            "payload": {
                "allAlerts": [
                    {
                        "token": "foo-bar",
                        "type": "ALARM",
                        "scheduledTime": "2015-10-30T22:34:51+00:00"
                    }
                ],
                "activeAlerts": [
                ]
            }
        },
        {
            "header": {
                "namespace": "Speaker",
                "name": "VolumeState"
            },
            "payload": {
                "volume": 25,
                "muted": false
            }
        },
        {
            "header": {
                "namespace": "SpeechSynthesizer",
                "name": "SpeechState"
            },
            "payload": {
                "token": "zxcv8523",
                "offsetInMilliseconds": 0,
                "playerActivity": "FINISHED"
            }
        }
    ],
    "event": {
        "header": {
            "namespace": "SpeechRecognizer",
            "name": "Recognize",
            "messageId": "messageId-123",
            "dialogRequestId": "dialogRequestId-321"
        },
        "payload": {
            "profile": "CLOSE_TALK",
            "format": "AUDIO_L16_RATE_16000_CHANNELS_1"
        }
    }
}

--this-is-a-boundary
Content-Disposition: form-data; name="audio"
Content-Type: application/octet-stream

{{binary audio attachment}}
--this-is-a-boundary--

Response

:status = 200
content-type = multipart/related; boundary=this-is-a-boundary; type="application/json"

--this-is-a-boundary
Content-Type: application/json; charset=UTF-8

{
    "directive": {
        "header": {
            "namespace": "SpeechSynthesizer",
            "name": "Speak",
            "messageId": "ewq-321",
            "dialogRequestId": "dialogRequestId-321"
        },
        "payload": {
            "url": "cid:1234",
            "format": "AUDIO_MPEG"
            "token": "kr17447380422"
        }
    }
}

--this-is-a-boundary
Content-Type: application/octet-stream
Content-ID: <1234>

{{binary audio attachment}}
--this-is-a-boundary--

Example 2:

The following example shows a Recognize event that receives one Speak directive and one Listen directive as a response.