Progressive Response REST API Reference

Note: Sign in to the developer console to build or publish your skill.

Use the Progressive Response REST API to send an interim response for Alexa to play until your skill sends the full response. Progressive responses might include confirmation that your skill is processing the answer, such as "Please wait while I look that up for you …."

For more details about progressive responses, see Send the User a Progressive Response.

Important: Progressive responses don't change the overall time allowed for a response. When a user invokes a skill, the skill has eight seconds to return a full response. The skill must finish processing any progressive responses as well as the full response within this time.

API endpoint

Use one of the following API hosts, based on the region where the customer is located:

North America: https://api.amazonalexa.com
Europe: https://api.eu.amazonalexa.com
Far East: https://api.fe.amazon.com

You can find the API endpoint in the context.System.apiEndpoint retrieved from a request from Alexa, such as the LaunchRequest or IntentRequest.

Authentication

Each API request must have an authorization header whose value is the context.System.apiAccessToken retrieved from a request from Alexa, such as the LaunchRequest or IntentRequest.

Operations

The Progressive Response API includes the following operations.

Operation	HTTP method and URI
Send directive	`POST /v1/directives`

Send directive

Send a directive to instruct Alexa to speak the provided text, generated with Speech Synthesis Markup Language (SSML).

Important: You can send up to five progressive responses for a single user request. Beyond this limit, your request receives an HTTP 401 Unauthorized response.

Request

To send a directive, you make a POST request to the /v1/directives resource.

Request path and header example

Copied to clipboard.

POST /v1/directives
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`access token`	Header	Access token used for the customer. Set to `request.context.System.apiAccessToken` from the `LaunchRequest` or `IntentRequest`.	String	Yes

Request body example

Copied to clipboard.

{
    "header": {
        "requestId": "amzn1.echo-api.request.1"
    },
    "directive": {
        "type": "VoicePlayer.Speak",
        "speech": "<speak>This text is spoken while your skill processes the full response.</speak>"
    }
}

Request body properties

Property	Description	Type	Required
`header`	Identifies the specific request sent from Alexa to your skill.	Object	Yes
`header.requestId`	Unique ID for the request. Set to `request.requestId` from the `LaunchRequest` or `IntentRequest`.	String	Yes
`directive`	Defines the directive to send to Alexa.	Object	Yes
`directive.type`	Type of directive. Valid value: `VoicePlayer.Speak`.	String	Yes
`directive.speech`	Text for spoken content, wrapped in SSML `<speak>` tags. Valid for `VoicePlayer.Speak` only. You can use other SSML tags within the `<speak>` tags with the following limits: The maximum text size is 600 characters. This value is smaller than the `outputSpeech` property. You must wrap the text in `<speak>` tags, even if you don't use any other SSML tags within the string. If you use the SSML `<audio>` tag, the maximum audio length is 30 seconds. This value is shorter than the normal audio allowed in this tag. For additional MP3 requirements, see `<audio>`.	String	Yes

Response

A successful response returns HTTP 204 No Content to indicate that Alexa processed the request successfully. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message. An error status code indicates that Alexa didn't speak the text.

If a properly formed request fails, you can safely resend it to retry. Alexa doesn't play the same content multiple times.

Response body example

The response has no body.

Response body properties