Progressive Response REST API Reference


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.

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).

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

The response has no body.

HTTP status codes

Status Description

204 No Content

Alexa processed the progressive response successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid, such as a missing or invalid requestId.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, the requestId represents a request that's no longer applicable, such as after the skill sends the full response.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.


Was this page helpful?

Last updated: Aug 01, 2024