Define Responses from Alexa for Alexa Conversations

When an interaction between Alexa and the user triggers Alexa Conversations to invoke an API in your skill code, you use a response to format and return the API output to the user. You do so by using the Alexa text-to-speech (TTS) engine.

For example, when the user asks a weather skill for the weather, the output of the GetWeather API might be the city, date, high temperature, and low temperature as follows.

User: What's the weather?
Alexa: In what city?
User: Seattle.
Alexa: In Seattle, it's 70 degrees.

You define a response for Alexa to pass this information to the user with TTS that includes variables. In the previous example, you might define the TTS to be In {}, it's {returnedWeather.temperature} degrees.

You specify the TTS or visual response as Alexa Presentation Language for Audio and Alexa Presentation Language (APL), respectively.

Get Started

To get started with Alexa Conversations, you can step through a pet match skill-building tutorial, download the code for a pizza-ordering reference skill, or use an Alexa-hosted sample skill template that includes an Alexa Conversations skill configuration and back-end skill code.

Overview of responses

Responses consist of the following elements:

  • Audio response – (Required) The output is the text-to-speech (TTS) and, optionally, the visual response that Alexa provides to the user. The TTS is in an Alexa Presentation Language (APL) for Audio document. For details about APL for Audio, see APL for Audio Reference. APL-A documents can incorporate input arguments that pass into the response.

    Continuing the previous example, the APL-A document might contain the following text in its content field: In {}, it's {returnedWeather.temperature} degrees.

  • Visual response – (Optional) To specify a visual response, you use Alexa Presentation Language. For details, see Alexa Presentation Language (APL).

  • Arguments – (Optional) If a response requires information from the API that triggered it, you specify input arguments to the response. For example, perhaps you create a weather skill. Your GetWeather API might return a returnedWeather slot type that contains a field for the city, date, high temperature, and low temperature. Alexa Conversations passes these fields to the response template as an input argument.

Use multiple responses

To reduce the number of dialogs, you can have multiple responses in a single Alexa turn. Adding multiple responses reduces the number of dialogs because you can cover any combination of arguments (when requesting arguments), confirming arguments, or confirming an API. The user interface also suggests responses when possible, to help you increase coverage of dialog variations.

Confirm arguments

Alexa can confirm arguments in a single turn, and then, if the user denies the arguments, Alexa can request the arguments again. To use this feature, use the Confirm Args or Confirm API dialog act when you annotate an Alexa response. For the response, specify a prompt such as, "Do you want the weather for {city} on {date}?" For a tutorial that demonstrates how to confirm arguments, see Tutorial: Confirm API Arguments for Alexa Conversations.

Create a response

To create a response during dialog annotation, complete the following steps. For a dialog annotation tutorial that includes creating a response, see Tutorial: Annotate a Dialog.

To create a response during dialog annotation

  1. As a starting point, follow steps 1-3 in Tutorial: Annotate a Dialog.
  2. Click anywhere within the ALEXA: line "In Seattle, it's 70 degrees."
  3. For the dialog act, select API Success.
  4. Next to API to Invoke, click +, and then select the GetWeather API that you created.
  5. Under the API selection box, edit the Variables → Arguments mapping to say returnedWeatherreturnedWeather0.
    If you don't see a section for the variable-to-argument mapping, click the box where you selected the GetWeather API, and the variable-to-argument mappings should appear.
  6. Under Response, click Select a Response, and then click Create New Response.
  7. For the response name, enter return_weather.
  8. Under Audio Response (required), click Select an audio response, and then click Create a new prompt.
  9. For Audio Response Name, enter returned_weather_prompt.
  10. Under Alexa Prompts, click What will Alexa say to the user?, and then enter In {}, it's {returnedWeather.temperature} degrees., and then click +.
    Do not forget to click +.
  11. Directly under where you just entered the Alexa speech, click Save.
  12. Scroll down past Visual Response, to the Arguments section.
    You should see a slot for returnedWeather, which was automatically extracted from the sample Alexa prompt in the previous step.
  13. For the returnedWeather slot type, select the returnedWeather slot type that you created.
  14. In the header bar, click Save, and then return to the dialog annotation tool.
    You now need to edit the API definition and add the response.
  15. In the left panel, select API Definitions, and then select GetWeather.
  16. Under Responses, select the return_weather response that you created.
  17. In the header bar, click Save.
  18. Back in your dialog, click anywhere within the Alexa line "In Seattle, it's 70 degrees" again.
    An Alexa Response panel appears on the right.
  19. In the Alexa Response panel, scroll down and, under Response, click return_weather.
    Below the response, a variable-to-argument section appear.
  20. Under Response, edit the Variables → Arguments mapping to returnedWeather0returnedWeather.
  21. In the header bar, click Save.
  22. In the left pane, expand API Definitions, and then click the GetWeather response that you created.
  23. In the header bar, click Save.