Alexa.Presentation.APLA Interface Reference

The Alexa.Presentation.APLA interface provides directives for rendering an audio response defined in an APL document.

RenderDocument directive

Instructs the device to play the audio response defined in the specified document. You can also optionally provide one or more datasources to bind content to a document.

The following example passes a full document to play as an audio response:

{
  "type": "Alexa.Presentation.APLA.RenderDocument",
  "token": "developer-provided-string",
  "document": {
    "version": "0.8",
    "type": "APLA",
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "item": {
        "type": "Selector",
        "items": [
          {
            "type": "Speech",
            "when": "${payload.user.name == ''}",
            "content": "Hello!"
          },
          {
            "type": "Speech",
            "content": "Hi ${payload.user.name}!"
          }
        ]
      }
    }
  },
  "datasources": {
    "user": {
      "name": "John"
    }
  }
}

Properties

Name Description Type Required

datasources

Map of data source objects to provide data to the document. Use this to separate your template from the data. See Data-binding Evaluation and Data-binding Syntax.

Object

No

document

An object representing the APL document to convert to an audio response and play on the user's device.

When document.type is "APLA", document must contain the complete JSON document.

When document.type is "Link", document must contain the src property with the URL link to the document.

Object

Yes

document.src

The URL that identifies the document in the authoring tool. For APLA, the link has the following syntax: doc://alexa/apla/documents/<RESPONSE-NAME>. Replace <RESPONSE-NAME> with the name you used when saving the document. Don't include this property when document.type is APLA.

doc://alexa/apla/documents/<RESPONSE-NAME>

No

document.type

Indicates the type of document to send. Set to "APLA" when document contains the full document object. Set to "Link" when document.src contains a document link.

APLA | Link

No

token

A unique identifier for the presentation. Each document is considered an independent presentation. This is used to associate future events and directives with the appropriate presentation.

String

Yes

type

Always Alexa.Presentation.APLA.RenderDocument.

String

Yes

Update your skill to use a linked document

You can save an APLA document in the authoring tool and then use a link to that document in the RenderDocument directive. This means you don't need to export the JSON for your document and copy it into your code.

A link to an APLA document in the authoring tool has the following syntax:

doc://alexa/apla/documents/<RESPONSE-NAME>

The <RESPONSE-NAME> is the name you used when saving the document in the authoring tool.

The following example uses a link to specify a linked document specified by the src for the audio response:

{
   "type": "Alexa.Presentation.APLA.RenderDocument",
   "token": "developer-provided-string",
   "document": {
     "type": "Link",
     "src":  "doc://alexa/apla/documents/<RESPONSE-NAME>",
   },
   "datasources": {
     "user": {
       "name": "John"
     }
   }
 }

Combine RenderDocument with outputSpeech and reprompt

APL for audio works alongside the existing outputSpeech and reprompt properties.

When your response includes both outputSpeech and the RenderDocument directive, the device renders the outputSpeech first, followed by the audio defined in the APL document. During an interaction in which Alexa listens for the user to response (shouldEndSession is false), the reprompt plays if the user doesn't respond within a few seconds.

The following example illustrates a response that includes outputSpeech, reprompt, and RenderDocument. The document content is omitted for brevity.

Copied to clipboard.

This sample code uses the Alexa Skills Kit SDK for Node.js (v2).

return handlerInput.responseBuilder
     .speak("hello")
     .addDirective({
            "type": "Alexa.Presentation.APLA.RenderDocument",
            "token": "launch_a",
            "document": {
                 "version": "0.8",
                 "type": "APLA",
                 "mainTemplate": {
                      "parameters": [
                           "payload"
                      ],
                     "item": {}
                 }
            }
     })
     .reprompt("This is the re-prompt.")
     .getResponse();

Service Interface Reference (JSON)

Request Format and Standard Request Types:

Interfaces: