Defining Response Templates

When defining our sample dialog, we referenced a handful of APL-A documents that serve as a response to the user. Three of them ask the user for trip information, one asks the user to confirm the dialog, and one other ends the conversation with a final response. While we referenced them in our sample dialogs, we haven’t yet defined them. Now it’s time to create the APL-A documents that our conversation will use to communicate with the user.

Response templates can be either APL or APL-A documents. For simplicity, our skill will only use APL-A documents, but feel free to experiment and alter the skill to send graphical content with APL documents.

Regardless of whether you use APL-A or APL responses, you’ll need to put your documents under the project’s skill-package/response/prompts directory. Each response will need to be in a subdirectory named the same as the response, with a single document.json file inside that is the APL or APL-A document.

For example, our sample dialog references a response named request_destination_apla. To define such an APL-A template, we need to create a file named document.json in skill-package/response/prompts/request_destination_apla. Such a template might look like this:

Here, there’s a single APL-A “Speech” component that asks the user where they want to go. To mix things up a little, feel free to expand this to use a “Selector” component with “randomItem” strategy to phrase the question differently each time it is asked and to make Alexa seem less robotic and scripted.

The response APL-A documents for the trip dates and dialog confirmation are very similar, just with different questions being asked. For example, here’s the APL-A document used to ask the user to specify a departure date:

And here’s one that asks for a return date:

By now, you’ve likely observed a pattern in the structure of these APL-A documents. Ultimately only the content of the Speech element is different. However, even though these APL-A documents are very similar, you are welcome to use any valid APL-A document, including more complex documents that mix sounds and music if you’d like.

But, for the sake of completeness, here’s another APL-A document that the dialog uses to ask for confirmation:

The APL-A document that defines the final response is slightly different in that it accepts model data and uses it to fill in a placeholder in the Speech element’s content:

The scheduleTripResult parameter passed into the response by the dialog is used here to tell the user to enjoy their trip to whatever planetary destination that they have chosen. For example, if the user has asked for a trip to Venus, then scheduleTripResult will be set to “Venus” and the response from Alexa will be “Enjoy your trip to Venus!”

One important thing to understand about these response documents is how they are imported into ACDL. All of them will be placed in a prompts namespace and will have a name that is the same as the directory that holds the document.json file. For the templates we’ve defined, the import lines in ACDL will look like this:

Now we have created our conversation model and defined a handful of APL-A documents that serve as responses from Alexa in the course of a dialog. The one thing we’ve not done yet, though, is write the fulfillment code that sits behind the scheduleTrip action. Let’s do that now.