Send the User a Progressive Response

If your skill takes time to prepare a full response to the user request, you can send progressive responses to keep the user engaged. A progressive response is Speech Synthesis Markup Language (SSML) content, including text-to-speech and short audio, that Alexa plays to the user while waiting for the full skill response.

To send a progressive response, call the Progressive Response REST API to send the content to Alexa.

When to send progressive responses

You can use progressive responses to accomplish the following goals:

  • 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 before sending the full response.
  • Reduce the user perception of latency in your skill 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 during the external interaction, your skill can return the following message to let the user know that the skill is working on the request.

User: Alexa, ask Ride Hailer to book a ride to the airport. (Normal IntentRequest sent to the Ride Hailer 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 can't send progressive responses from any other request types, such as AudioPlayer requests.

Steps to send a progressive response

To send a progressive response, complete the following steps:

  1. Get the required data from the incoming LaunchRequest or IntentRequest.
    You need the context.System.apiAccessToken and request.requestId to construct a valid Progressive Response API request.
  2. Call the Send directive API with the content that you want Alexa to speak.
    The content must be valid SSML wrapped in <speak> tags.
  3. Complete normal skill processing.
  4. After the progressive response completes, return the full skill response to Alexa.
    You can send up to five progressive responses before you send the full skill response.
    However, you can't send any more progressive responses after you return the full response.

Progressive responses are only played on the device if they arrive before the Alexa service receives the full response from the skill. For the best user experience, your skill should wait until the progressive response completes before you send the full response. The Progressive Response API returns an HTTP 204 No Content status code after the progressive response is ready to play on the device.

Use audio within a progressive response

You can embed short recorded audio within a progressive response with the SSML <audio> tag. The audio can't be longer than 30 seconds, which is shorter than the normal audio length allowed in the <audio> tag. For additional MP3 requirements, see <audio>.

For optimal performance, Amazon recommends that you host your MP3 files for SSML responses in close proximity to where your skill is hosted. For example, if the Lambda function for your skill is hosted in the US West (Oregon) region, you will get better performance if you upload your MP3s to a US West (Oregon) S3 bucket.

In addition to using S3 for hosting, Amazon recommends that you use a content delivery network (CDN) such as AWS CloudFront for hosting media assets to prevent throttling under high load.

Was this page helpful?

Last updated: May 29, 2024

DevAssistant
Amazon Developer Assistant