Response Prompt Files for Alexa Conversations

Response prompt files contain the speech that Alexa says to the user as Alexa Presentation Language for Audio (APLA).

File location

When you create an Alexa Conversations skill by using the Alexa Skills Kit Command-Line Interface (ASK CLI), the response prompt files are in <skill-directory>/skill-package/response/prompts/.

Each response prompt file is named document.json and resides in a directory named after the response prompt. For example, the response prompt file for the AlexaConversationsBye response prompt is <skill-directory>/skill-package/response/prompts/AlexaConversationsBye/document.json.

The <skill-directory>/skill-package/response/prompts/ directory contains both built-in responses as well as any responses you define. You can update the built-in responses with customized speech for your skill. For example, you can update the AlexaConversationsWelcome response with your own greeting.

File contents

Response prompt files are in APLA format (JSON) using the syntax defined by the APL for Audio Reference. APLA is a feature that many types of Alexa skills use, so the file format of response prompt files is not unique to Alexa Conversations.

The following example shows a simple APLA response prompt file. Because this response prompt uses RandomSelector, Alexa randomly selects one of the three responses in the items array.

{
  "type": "APL-A",
  "version": "0.9",
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "item": {
      "type": "RandomSelector", 
      "description": "",
      "items": [
        {
          "type": "Speech",
          "contentType": "text",
          "content": "Speech variation 1. Refer to arguments using syntax ${payload.argumentName}.",
          "description": "Variation 1."
        },
        {
          "type": "Speech",
          "contentType": "text",
          "content": "Speech variation 2. Refer to arguments using syntax ${payload.argumentName}.",
          "description": "Variation 2."
        },
        {
          "type": "Speech",
          "contentType": "text",
          "content": "Speech variation 3. Refer to arguments using syntax ${payload.argumentName}.",
          "description": "Variation 3."
        },     
        ...           
      ]
    }
  }
}

You put the speech for Alexa in the content fields. By including several objects in the items array, you can add more variations of how you want Alexa to render the response to the user.

For details about how to customize fields in APLA, see APL for Audio Reference.

Examples

The following is an example of a response prompt that confirms user-provided arguments before calling a weather API.

{
  "type": "APL-A",
  "version": "0.9",
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "item": {
      "type": "RandomSelector",
      "description": "",
      "items": [
        {
          "type": "Speech",
          "contentType": "text",
          "content": "Just to confirm, you want to get the weather report for ${payload.date} in ${payload.cityName}?",
          "description": "APL-A for confirming API arguments."
        }
      ]
    }
  }
}

The following is an example of a response prompt that reports the outcome of a weather API. Alexa renders the response when the conditions in when evaluate to true. When items contains multiple components, Alexa renders the first components where when evaluates to true.

{
  "type": "APL-A",
  "version": "0.9",
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "item": {
      "type": "RandomSelector",
      "description": "Change 'type' above to try different Selector Component Types like Sequential",
      "items": [
        {
          "when": "${payload.weatherResult != null && payload.weatherResult.cityName != null && payload.weatherResult.highTemp != null && payload.weatherResult.lowTemp != null}",
          "type": "Speech",
          "contentType": "text",
          "content": "In ${payload.weatherResult.cityName}, it's a high of ${payload.weatherResult.highTemp} degrees and a low of ${payload.weatherResult.lowTemp} degrees. Do you want to get rain information?",
          "description": "APL-A for notifying the user of the API response from GetWeather()"
        }
      ]
    }
  }
}
Was this page helpful?

Last updated: Nov 27, 2023