Build Documents in the Developer Console

Use tools in the developer console to build, preview, and test an Alexa Presentation Language (APL) document. An 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 Multimodal Response Builder

The Multimodal Response Builder provides a guided experience to create a visual response in three steps:

  1. Select from a set of templates designed to look good across a broad range of devices.
  2. Customize the response by specifying the content to display within the template
  3. Preview the response both in the developer console and on a device.

After you finish customizing the response, the Multimodal Response Builder generates a code example you can copy into a request handler in your skill to display the response. Rebuild the interaction model for your skill and then test your skill on a device or with the developer console simulator.

You can create a new document in the Multimodal Response Builder to get started, and then edit the document in the full authoring tool if you want to do more complex customizations.

To open the Multimodal Response Builder

  1. In the developer console, open the skill for which you want to create this document.
  2. In the sidebar, 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

Use the authoring tool within a skill

The authoring tool provides a complete authoring environment for APL. You can start from scratch or start from an existing template. You can also import Lottie animations and scalable vector graphics (SVG).

In the authoring tool, you have access to all APL features as you develop your template. The authoring tool is more powerful than the Multimodal Response builder, but it also requires more knowledge about how APL works.

For details about creating and editing APL documents, see Create and Edit an APL Document.

For the language reference for APL, see the following:

Experiment with the authoring tool without a skill

You can open the authoring tool directly to experiment with APL without a skill. You can create a document from a sample template, lint your document, and view the rendered preview.

You must associate your document with a skill to save your work and use the following features:

  • Preview on a device
  • Transformers such as ssmlToSpeech and aplAudioToSpeech

To save your document with a skill

  1. Click the Save icon.
  2. Enter the Template Name.
  3. Select an existing skill from the Skill list and click Save.

Import a Lottie animation

Import animations in Lottie format into the authoring tool to use in your APL documents. Lottie is a JSON animation format that you can export from Adobe After Effects.

For details about importing a Lottie animation to use in your APL document, see Import a Lottie Animation.

Import a Scalable Vector Graphic (SVG)

Use the APL authoring tool to convert Scalable Vector Graphics (SVG) files into Alexa Vector Graphics (AVG) objects to use in your APL documents.

The SVG format is an XML-based markup language for describing vector graphics. AVG is a parameterized subset of SVG. You can display an AVG-defined graphic in your document with the VectorGraphic component.

For details about import an SVG, see Import a Scalable Vector Graphic (SVG) (Beta).

Import and export an APL document

You can export an APL document in JSON format. Export creates a JSON file with the document and data source. You can import an exported document to create a new document.

For details about import and export, see Import and Export APL Documents.

Preview an APL document

Use the authoring tool to preview how your document renders to your users.

For a visual response, you can see how the document looks on devices of different sizes. You can preview tap events, commands, video, and other aspects of the document. For an audio response, you can listen to the audio clip generated by the document.

For details about previewing and testing your document in the authoring tool, see Preview an APL Document.

Integrate your APL document into your skill response

To use your APL document in your skill, include the RenderDocument directive in the response your skill sends to Alexa. For a visual response, Alexa displays the document on the screen. For an audio response, Alexa plays the audio generated from the document.

When you send the RenderDocument directive, you must provide the document you want to display or play. Provide the document in one of the following ways.

Save the APL document in the authoring tool and pass the RenderDocument directive a link to the document. Your document remains associated with your skill in the developer console, and changes you make in the tools are reflected in the skill response.

To make a document available to the RenderDocument directive, you must build your interaction model in the developer console. When you make changes to the document in the authoring tool, rebuild the interaction model to make the updated document available to RenderDocument.

For details, see one of the following:

Embed the JSON for the document into your skill code

Copy the JSON for the document into your skill code and pass the full JSON for the document to the RenderDocument directive. When you make changes to the document, you must update your skill code.

For details about exporting the JSON for your document, see Import and Export APL Documents.

For examples that show how to send RenderDocument with the Alexa Skills Kit (ASK) SDK, see Add APL Support to Your Skill Code.

APL documents and the skill package

When you save an APL document in the authoring tool and build the interaction model for your skill, the developer console integrates the document into the skill package for your skill. The skill package contains resources that describe the skill, such as the skill manifest, the voice interaction model, the APL documents saved in the authoring tool, and other resources.

You can download the skill package for your skill to work with it offline, and then manage the skill with the ASK Command Line Interface (CLI), the Alexa Skill Management API (SMAPI), or the Alexa Skills Toolkit for Visual Studio Code (VS Code). These tools download APL documents for the skill into the skill-package/response folder.

If you use both the developer console and an offline tool to edit your skill, make sure that you keep the package in sync to avoid losing APL documents you created in the authoring tool. For example, you might lose work in the following scenario:

  1. You use the ASK CLI to download your skill to your local machine.
  2. Later, you create an APL document for this skill with the authoring tool to experiment with APL features. You save this document with the name MyNewAPLDocument.
  3. You make other, unrelated changes to the local version of skill, such as an edit to the skill manifest.
  4. You deploy these changes to your skill with one of the following commands:
    • ask deploy – Deploys a self-hosted skill.
    • git push – Deploys an Alexa-hosted skill.

The deployment step overwrites the skill package stored on the server with the version stored on the local machine. Because the local version doesn't include the document MyNewAPLDocument, this action deletes the document from the skill.

To prevent the loss of your work, make sure that the skill package on your machine matches the skill package stored on the Alexa service. Use the following guidelines:

  • When you create or update an APL document in the authoring tool, always build the skill. Your new or updated document isn't included in the skill package until you build the skill.
  • If you use the ASK CLI to manage your skill locally, download the latest version of your skill package before you deploy any local changes with the ask deploy or git push command. Back up the existing skill-package folder first, and then use the export-package command to download the latest version of the skill-package folder.
  • If you use the ASK Toolkit extension in VS Code, review the Skill Package Remote Sync Status section on the Deploy page before you deploy your local changes. If the tool indicates that your local skill package contents might not be up-to-date with Alexa, click the Export skill package link to back up your local skill package and download the latest.
Was this page helpful?

Last updated: Jun 30, 2023