Your Alexa Dashboards Settings

Send the User a Progressive Response

Your skill can send progressive responses to keep the user engaged while your skill prepares a full response to the user’s request. A progressive response is interstitial SSML content (including text-to-speech and short audio) that Alexa plays while waiting for your full skill response.

To send a progressive response, call the Progressive Response API and send a directive with the interstitial content.

When to Send Progressive Responses

You can use progressive responses to:

  • Send text-to-speech confirmations that your skill has received the request and is processing an answer.
  • Play short soundmarks associated with your skill.
  • Provide other engaging content to your users while waiting on the full response.

Progressive responses can also reduce the user’s perception of latency in your skill’s response.

For example, a skill to look up and book taxi rides might take a few seconds to access an external API to reserve a ride. Instead of remaining silent while the skill does this processing, you can return a message to let the user know that the skill is working on the request:

User: Alexa, ask Car-fu to book a ride to the airport. (Normal IntentRequest sent to the Car-Fu skill.)

Additional back-and-forth to collect all the information needed to fulfill this intent.
Alexa: OK, please wait while I look up details for your ride… (Progressive response while the skill prepares the full response.)
Alexa: OK, I’ve reserved your ride. It should arrive at your home in thirty minutes. (Normal response to the IntentRequest)

You can send progressive responses from the context of a current LaunchRequest or IntentRequest. You cannot send progressive responses from any other request types (such as AudioPlayer requests).

Steps to Send a Progressive Response

To send a progressive response, call the Progressive Response API and send a directive:

  1. Get the required data from the incoming request (LaunchRequest or IntentRequest). You need the apiAccessToken and requestId to construct a valid Progressive Response API request.
  2. Call the Progressive Response API and send a directive (such as VoicePlayer.Speak) with the content.
  3. Complete your normal skill processing and return the full skill response object. Note that you cannot send any more progressive responses after you return the response object.
The Progressive Response API and asynchronous responses

Progressive responses are only played on the device if they arrive before the Alexa service receives the skill’s full response object. If your skill sends the directive to the Progressive Response API asynchronously, it is possible for the full response object to arrive before the progressive response can be rendered on the device. In this case, the progressive response is skipped.

Get the Required Data for the Progressive Response API

Every call to the Progressive Response API requires an apiAccessToken and the requestID for the specific request sent to your skill. You can obtain both of these from the request sent to your skill.

Obtain the API Access Token

Use the apiAccessToken provided in the context object. The token is included in all requests sent to your skill.

The context object is included in all requests. You can access the apiAccessToken in context.System.apiAccessToken. Include the complete value of this property in your call to the Progressive Response API.

{
  "version": "1.0",
  "session": {},
  "context": {
    "AudioPlayer": {},
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.[unique-value-here]"
      },
      "user": {},
      "device": {},
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "AxThk..."
    }
  },
  "request": {}
}

In the above example, some objects and properties are removed for clarity.

Obtain the Request Identifier

The requestId identifies a specific request sent from Alexa to your skill. This value is included in all requests sent to your skill as part of the request object, such as LaunchRequest or IntentRequest. You can get the requestId from request.requestId.

{
  "version": "1.0",
  "session": {},
  "context": {},
  "request": {
    "type": "LaunchRequest",
    "requestId": "amzn1.echo-api.request.xxxxxxx",
    "timestamp": "2015-05-13T12:34:56Z",
    "locale": "en-US"
  }
}

In the above example, some objects and properties are removed for clarity.

Pass the entire value of the request.requestId property to the Progressive Response API.

API Endpoint and Geographic Location of the Skill

The endpoint for the Progressive Response API varies depending on the geographic location of your skill. You can get the correct base URL to use from the apiEndpoint value in the System object: context.System.apiEndpoint:

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.<skill-id>"
      },
      "user": {},
      "apiAccessToken": "AxThk...",
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {}
}

The examples in this document use the US endpoint (https://api.amazonalexa.com/).

For more about configuring your skill for multiple languages, see Develop Skills in Multiple Languages.

Send a Directive

This API call sends the specified directive to Alexa. Currently, the only supported directive is VoicePlayer.Speak. This instructs Alexa to speak the provided speech. You can provide the speech as plain text or SSML.

Your skill can send a maximum of five directive requests for a single user request. Any calls beyond this limit are rejected. Each directive request must be sent in a separate API call.

Endpoint: /v1/directives

Method: POST

Directive Request

POST https://api.amazonalexa.com/v1/directives HTTP/1.1
Authorization: Bearer AxThk...
Content-Type: application/json

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

Note that the actual token in the Authorzation header would be much longer than shown in this example.

Request Headers

Header Value Type Required

Authorization

An API access token in the format: Bearer apiAccessToken.

Get the apiAccessToken from the context.System.apiAccessToken property in the request sent to your skill.

string

yes

Content-Type

application/json

string

yes

Request Body

Provide the request body in a JSON object:

{ 
  "header":{ 
    "requestId":"amzn1.echo-api.request.xxxxxxx"
  },
  "directive":{ 
    "type":"VoicePlayer.Speak",
    "speech":"This text is spoken while your skill processes the full response."
  }
}
Parameter Value Type Required

header.requestId

The requestId for the user’s request.

Get the requestId from the request.requestId property included in the request sent to your skill.

The requestId must exactly match the identifier for the LaunchRequest or IntentRequest sent to your skill.

string

yes

directive.type

The directive type. VoicePlayer.Speak is the only supported directive.

string

yes

directive.speech

The text that Alexa should speak. This can be either plain text, or SSML.

  • The text must be no longer than 600 characters. This is smaller than the outputSpeech in the response object.
  • If you use the SSML <audio> tag, the audio cannot be any longer than 30 seconds. This is also shorter than the normal audio allowed in this tag. See <audio> for additional requirements around the MP3 files when using this tag.

string

yes

Directive Response

If Alexa is able to process and speak the text provided in your directive request, the service returns an HTTP 204 code. The response does not include any additional data. Any other status code indicates an error that prevented Alexa from speaking the text.

If a properly-formed directive request fails, you can safely resend it to retry. Alexa does not play the same content multiple times.

Possible Responses

The directive request can return the following codes:

Response Description
204 No Content Alexa successfully processed the directive.
400 Bad Request The requestId is either missing from the request, or is structurally incorrect.
403 Forbidden The authentication token is invalid or doesn’t have access to the resource. This is also returned if the requestId represents a request that is no longer applicable, such as when the progressive response is received after skill’s full response.
405 Method Not Allowed The method is not supported.
429 Too Many Requests The skill has been throttled due to an excessive number of requests.
500 Internal Error An unexpected error occurred.