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.

Multimodal Response Builder Authoring tool

Start from one of 12 templates based on APL and Alexa best practices.

  • Start from scratch
  • Start from a limited set of templates
  • Upload an existing document, a Lottie animation, or an Scalable Vector Graphic (SVG).

Get started without any prior APL knowledge.

Requires APL knowledge.

Customize a template by editing the content to display in a subset of the template fields. Provides access to a limited set of APL features, based on the template.

Fully customize a document with APL components. Provides access to all APL features. You can use built-in linting and code completion features to help you build your document.

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:
  6. In the upper-right corner, click Save (Save icon ) 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:
  7. In the upper-right corner, click Save (Save icon ) 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.

    • 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.

Select a template page in the Multimodal Response Builder
Select a template page in the Multimodal Response Builder

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.

Library of responsive templates and APL examples
Library of responsive templates and APL examples

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.

Library of audio templates
Library of audio templates

Build a visual response in the authoring tool

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

Main authoring tool interface
Main authoring tool interface
UI Element Description

1

Code View / GUI View — Switch between a graphical view of the in the document components and the JSON code view for the document. You can view the GUI View for APL and GRAPHICS sections with the GUI View.

2

Left-hand toolbar — Buttons to switch between the sections of the APL document and the data sources.

3

Top toolbar — Buttons to preview, integrate, save, and export the document.

  • Use Live Preview Mode to switch to preview mode and test interactions and commands in your document. This mode also lets you view log messages generated with the Log command.
  • Use Integrate with Skill to generate the code to display the document. You can copy this code to your skill.
  • Use the export button to download the document as a JSON file.

4

Viewport profiles toolbar — Buttons to switch the preview pane between different viewport profiles. Viewports are organized by device type (such as "Hub" and "Mobile") and then viewport (such as "Medium Hub"). Select specific example devices from the drop down list. For more details, see Preview a visual response.

5

Size range drop-down list — For viewport profiles that support a range of sizes, this list displays sizes of popular devices within the range.

6

Document preview pane — Displays an approximation of how your document looks on different viewports. When in normal authoring mode, click the preview pane to select components. You can also drag components to change your design. To test touch events and commands, switch to preview mode. For more details, see Preview a visual response.

7

Components palette — Displays all the core APL components. Drag components from this palette onto the display shown in the preview pane to build your document.

8

Show on — Menu to push your document to a device associated with your Amazon developer account. Select the device from the drop-down list, and then click Send to Device to see your document on the physical device.

Toolbar buttons

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

Toolbar button Description

APL toolbar button

APL — Displays the full APL document in either code view or GUI view. For the full JSON syntax, see APL Document.

DATA toolbar button

DATA — Displays the JSON code for your data sources. For the full syntax of a data source, see APL Data Sources.

SOURCES toolbar button

SOURCES — Displays the JSON code for sources required to test the aplAudioToSpeech transformer with your document. See Test the APL for Audio transformer.

STYLES toolbar button

STYLES — Displays the JSON code for the styles property of the document. See APL Style Definition and Evaluation.

DOCUMENT toolbar button

DOCUMENT — Displays the JSON code for the import property, as well as additional top-level Document properties.

RESOURCES toolbar button

RESOURCES — Displays the JSON code for the resources array. See APL Resources.

GRAPHICS toolbar button

GRAPHICS — Displays the collection of Alexa Vector Graphics defined in the graphics property in your document. You can view and edit the graphics as JSON code or in a GUI view.

SETTINGS toolbar button

SETTINGS — Displays the JSON code for the settings property. This code can contain a set of key-value pairs that define document-wide settings.

COMMANDS toolbar button

COMMANDS — Displays the JSON code for the commands property. This code can contain a set of user-defined commands that you can use within your document.

ONMOUNT toolbar button

ONMOUNT — Displays the JSON code for the onMount property. This code can contain an array of commands to run when the document initially displays on the screen.

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.

Authoring tool Layouts pane
Authoring tool Layouts pane
UI element Description

1

Layouts — See all the components in your document in a hierarchical view. Select a component, and then click Add Component to add a component to the document.

2

Component properties form — Fill in the properties for the selected component or layout.

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.

Authoring tool for an audio response
Authoring tool for an audio response
UI element Description

1

Left-hand toolbar – Buttons to switch between the JSON code for the document and the data sources.

2

Top toolbar – Buttons to save and download the document. You can download the document as an MP3 file or as the JSON code.

3

Edit pane – Pane for editing the JSON code for the document and the data sources.

4

Preview button / Preview controls – Buttons for previewing the audio. For details about previewing an audio response, see Preview an audio response.

Toolbar buttons

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

Toolbar button Description

APLA icon

APLA – Displays JSON code for the entire document. For the full syntax, see Document (APL for Audio).

DATA toolbar button

DATA – Displays the JSON code for your data sources.

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

APL icon

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 authoring tool flags incorrect values for properties
The authoring tool flags incorrect values for properties
Error when a property name is misspelled
Error when a property name is misspelled

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.

Automatically fill in allowed values
Automatically fill in allowed values

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

JSON editor for an APL for audio document

APLA icon

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

DATA icon

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:


Was this page helpful?

Last updated: Mar 11, 2024