Create and Edit an APL Document

An Alexa Presentation Language (APL) document is a JSON structure that defines a template for a skill response. The document can define either a visual response or an audio response.

Use the developer console to create and manage APL documents.

Create APL documents

Within the developer console, you can create visual responses and audio responses.

• A visual response uses the APL document format. When you send the document to Alexa with the RenderDocument directive, Alexa displays the content on the device.
• An audio response uses the APLA document format. When you send the document to Alexa with the RenderDocument directive, Alexa plays the audio generated by the document.

The following sections show how to create visual and audio responses in the developer console.

Create a visual response

The developer console offers two different tools for creating a visual response with APL. If you're new to APL, start with the Multimodal Response Builder to create a new response in three steps, without prior APL knowledge. If you're more experienced with APL, or if you want to fully customize your response, use the authoring tool instead.

The following table summarizes the differences between these two tools.

You can also choose to start with the Multimodal Response Builder, and then switch to the authoring tool later if your response requires more customization.

To create a visual response by customizing a pre-built template

1. In the developer console, open the skill for which you want to create this document.
2. In the left-hand navigation, click Multimodal Responses.
3. Click Create with Response Builder.
4. Step through the pages to complete the three steps
   • Select a template. The set of templates includes responsive templates as well as other visual designs.
   • Customize
   • Preview and test

To create a new visual response in the authoring tool

1. In the developer console, open the skill for which you want to create this document.
2. In the left-hand navigation, click Multimodal Responses.
3. Click Create with authoring tool.
4. Choose how you want to create your document:
   • To start from a sample template, find the template in either the Responsive Templates or Explore APL section. Click the template you want to use. For details about the templates, see Use a pre-built template.
   • To start from a blank document and build your own, click Blank Document.
   • To import an existing JSON document click Upload. For details about how to format your document for upload, see Import an APL document from a JSON file.
   • To import an existing Lottie animation, click Upload. For details about how to convert a Lottie animation to an APL animation, see Import a Lottie Animation.

   The new document opens in the authoring tool.

5. Update and preview your document. See the following:
   • Build a visual response
   • Preview an APL Document
6. In the upper-right corner, click Save ( ) to save the document with your skill. When prompted, enter a name for the document.

Create an audio response

An audio response defines and arranges a set of audio clips. You can create a new audio response from a template or from scratch.

To create a new audio response

1. In the developer console, open the skill for which you want to create this response.
2. In the left-hand navigation, click Multimodal Responses.

3. Click Audio. The authoring tool filters the list of APL documents to display audio responses saved with the skill.

4. Click Create Audio Response.
5. Choose how you want to create your document:
   • To start from a sample template, click the template.
   • To start from a blank document and build your own, click Blank Document.
   • To import an existing JSON document, click Upload and then select the file to import.
6. Update and preview your document. See the following:
   • Build an audio response
   • Preview an APL Document
7. In the upper-right corner, click Save ( ) to save the document with your skill. When prompted, enter a name for the document.

Manage existing documents

You can edit, delete, clone, and download existing documents in the developer console.

To manage existing documents

1. In the developer console, open the skill that the document was saved to.
2. In the left-hand navigation, click Multimodal Responses.
3. Click either Audio or Visual to see the list of existing documents.
4. From the list of documents, click the link for the action you want to do:
   • Edit – (Audio response) Open the document in the APL for audio authoring tool.
   • Edit in Response Builder – (Visual response) Open the document in the Multimodal Response Builder. This option is available for documents created with the response builder.

   • Edit in Authoring Tool – (Visual response) Open the document in the authoring tool for visual responses.

     Important: After you open a document in the authoring tool, you can't edit it with the Multimodal Response Builder.
   • Integrate with skill – (Visual response) Open a page with code snippets you can copy into your skill code. The provided snippets show how to use the RenderDocument directive to display your APL content on the device.
   • Delete – Delete the document.
   • Clone – Make a copy of the document in the same skill.
   • Download – Download a JSON file with the document, datasources, and sources. This option is equivalent to exporting the document. For details, see Import and Export APL Documents.

Use a pre-built template

The developer console provides a library of templates to use as a starting point for your response. For a visual response, access templates in either the Multimodal Response Builder or the authoring tool. For an audio response, the templates are available in the authoring tool.

Multimodal Response Builder templates

You can choose from several templates, then customize the template with your content in a simpler interface.

Authoring tool templates

The authoring tool provides templates organized into two sections:

• Responsive templates – Full screen templates that look good on different devices with screens. For example, the Text List template presents a scrolling list of text items with a background and header. You provide the content to display in a data source.
• Explore APL – Additional templates that illustrate more designs and APL possibilities.

Each template uses a data source to provide the content displayed in the layout. After you select a template, click DATA to see the data source. For example, Text List includes a background image and the list items. Modify the content of the data source JSON to see how the template displays different content.

For more information about navigating the authoring tool interface, see Build a visual response.

Audio response templates

The authoring tool for APL for audio provides templates that demonstrate key features, such as mixing audio.

For more information about navigating the authoring tool interface, see Build an audio response.

Build a visual response in the authoring tool

The core areas of the authoring tool are visible all the time.

Toolbar buttons

The following table summarizes the options on the left-hand toolbar.

Edit your document with the Layouts pane (GUI view)

The GUI View option displays the Layouts pane, which shows components, layouts, and graphics in a hierarchical view. For the APL document, the pane shows the mainTemplate first, followed by any custom layouts defined in the layouts property. You can drag the components within the Layouts pane to rearrange the hierarchy.

Select a component or layout in the pane to highlight it on the preview pane.

For the GRAPHICS section, the layouts pane shows a thumbnail of each vector graphic defined in the graphics property. Select a graphic to edit its properties.

To add a component to mainTemplate or a custom layout

1. In the Layouts pane, select the component that should be the parent of the new component.

   You must select a component that can contain child components, such as mainTemplate or Container.

2. In the upper-right corner of the pane, click Add Component.
3. Select Child Components.

4. Select the Component, and then click Add.

   If your document includes any custom layouts, you can also choose a layout instead of a component.

5. In the pane to the right, edit the properties of the new component.

To create a custom layout

1. In the Layouts pane, select mainTemplate.
2. In the upper-right corner of the pane, click Add Component.
3. In the drop-down list, select Custom Layout.
4. Enter the New Layout Name, and then click Add.
5. Add components to the new layout as needed.

To update the properties for a component

• Select the component in the hierarchy, and then edit the property values in the pane next to the Layouts pane.

Build your document with drag and drop

You can edit your document visually by clicking and dragging components in the document preview pane:

• Click a component in the components palette and drag it to the document.
• When you drag a Text, Image, or Video component to an empty preview, the authoring tool automatically puts the component inside a Container.
• Select GUI View and then click a component in the Layouts pane to highlight that component on the preview. You can also click a component in the preview pane to highlight it in Layouts
• Drag components within the preview to rearrange them.

Build an audio response

The core areas of the authoring tool are visible all the time.

Toolbar buttons

The following table summarizes the options on the left-hand toolbar.

After you update the JSON code for your APL for audio document, you can generate and preview the audio. For details, see Preview an audio response.

Edit the JSON code for the document and data sources

The authoring tool includes JSON editors for the document and for the data sources.

The JSON editor provides basic validation for JSON syntax errors, such as misplaced commas. For a visual response, the editor also shows warnings if you include properties that don't belong on a component.

JSON editor for an APL document

The APL toolbar button displays the JSON for the full document. You can also use the additional toolbar buttons to view and edit the JSON for specific parts of the document, such as the styles and resources properties.

The code editor provides linting for coding errors, such as missing required properties, incorrect use of APL attributes, and other syntax issues. Error messages provide links to documentation and details about how to correct the problem.

The code editor also supports auto-completion of APL language constructs. As you type, the tool shows possible APL properties, primitive components, commands, and event handlers.

For the full syntax for an APL document, see APL Document.

JSON editor for an APL for audio document

The APLA toolbar button displays the JSON for the full document. For the full syntax for an APL for audio document, see Document (APL for Audio).

JSON editor for the data sources

The DATA toolbar button displays the JSON for the data sources for the document. Use this editor to build a JSON structure that your document can access with data binding.

Each data source must be a top-level property within the curly brackets ({}) and must have the name you use to reference the data source properties in your data-binding expressions.

The following example shows a valid data source for a visual response.

{
  "headlineTemplateData": {
    "type": "object",
    "objectId": "headlineSample",
    "properties": {
      "backgroundImage": {
        "contentDescription": null,
        "smallSourceUrl": null,
        "largeSourceUrl": null,
        "sources": [
          {
            "url": "https://d2o906d8ln7ui1.cloudfront.net/images/templates_v3/headline/HeadlineBackground_Dark.png",
            "size": "large"
          }
        ]
      },
      "textContent": {
        "primaryText": {
          "type": "PlainText",
          "text": "Welcome to The Daily Plant Facts"
        }
      },
      "logoUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/templates_v3/logo/logo-modern-botanical-white.png",
      "hintText": "Try, \"Alexa, what is the plant fact of the day?\"",
      "welcomeSpeechSSML": "<speak><amazon:emotion name='excited' intensity='medium'>Welcome to The Daily Plant Facts</amazon:emotion></speak>"
    },
    "transformers": [
      {
        "inputPath": "welcomeSpeechSSML",
        "transformer": "ssmlToSpeech",
        "outputName": "welcomeSpeech"
      }
    ]
  }
}

Assuming that the mainTemplate.parameters array in your document contains payload, you can reference properties in this data source with the following syntax: ${payload.headlineTemplateData.properties.textContent.primaryText.text}.

When you send the document to Alexa with the RenderDocument directive, your skill code must build out and include the data sources as part of RenderDocument in the datasources property. Alexa doesn't use the data sources saved in the authoring tool when rendering the actual response from a skill.

For more about data sources and data binding, see the following:

• Visual response: APL Data Sources
• Audio response: Data Sources (APL for Audio)

Related topics

• Build Documents in the Developer Console
• Import a Lottie Animation
• Import and Export APL Documents
• Preview an APL Document

Last updated: Mar 11, 2024