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:
- Select from a set of templates designed to look good across a broad range of devices.
- Customize the response by specifying the content to display within the template
- 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
- In the developer console, open the skill for which you want to create this document.
- In the sidebar, click Multimodal Responses.
- Click Create with Response Builder.
- 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.
- 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
To save your document with a skill
- Click the Save icon.
- Enter the Template Name.
- Select an existing skill from the Skill list and click Save.
Import a Lottie animation
For details about importing a Lottie animation to use in your APL document, see Import a Lottie Animation.
Import a Scalable Vector Graphic (SVG)
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
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.
Link to the APL document
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.
RenderDocument directive and a link to the document. The Integrate with Skill option is available on all APL documents saved in the developer console.
For details, see one of the following:
- For a visual response, see Link to an APL document saved in the developer console (Alexa.Presentation.APL).
- For an audio response, see Link to an APLA document saved in the authoring tool (Alexa.Presentation.APLA).
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
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:
- You use the ASK CLI to download your skill to your local machine.
- 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
- You make other, unrelated changes to the local version of skill, such as an edit to the skill manifest.
- 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
git pushcommand. Back up the existing
skill-packagefolder first, and then use the
export-packagecommand to download the latest version of the
- 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.
export-package command in the ASK CLI and the Export skill package link in the ASK Toolkit for VS Code download APL documents that are part of the skill package, which requires you to rebuild the skill. If you create a new document in the authoring tool, but you haven't yet built the skill, that new document isn't included in the download and might be deleted when you deploy local changes.
- Add Visuals and Audio to Your Skill
- APL Document
- Alexa.Presentation.APL Interface Reference
- Alexa.Presentation.APLA Interface Reference
Was this page helpful?
Last updated: Nov 28, 2023