Alexa.Presentation.APL 1.3

Note: Register now for Alexa Live, Amazon’s annual Alexa developer conference on July 20, 2022.

The Alexa.Presentation.APL interface contains APIs that provide a receipt of Alexa Presentation Language (APL) responses, consisting of documents and commands, to an Alexa Built-in device.

To learn how to integrate the APL Core Library, see the APL Core Library repository and documentation.

To learn more about visual responses for the Alexa Voice Service (AVS) and related APIs, see Alexa Presentation Language (APL) Overview.

Version changes

Important: The changes introduced in Alexa.Presentation.APL 1.3 depend on System 2.0 or higher because they leverage the new per-interface settings paradigm.

Support for token-based lazy loading:
- ADDED LoadIndexListData event
- ADDED LoadTokenListData event
- ADDED SendIndexListData directive
- ADDED SendTokenListData directive
Support for granted exceptions to characterize the use of APL extensions. To learn more, see APL Extensions:
- CHANGED RenderDocument directive to include new grantedExtensions and autoInitializedExtensions fields.

Capability assertion

A device may implement Alexa.Presentation.APL 1.3 on its own behalf, but not on behalf of any connected endpoints.

For new AVS integrations, assert support through Alexa.Discovery. However, AVS provides support for existing integrations through the Capabilities API.

Sample declaration

{
  "interface": "Alexa.Presentation.APL",
  "type": "AlexaInterface",
  "version": "1.3",
  "configurations": {
    "runtime": {
      "maxVersion": {{STRING}}
    }
  }
}

About APL runtime versions

Parameter	Description	Type
maxVersion	STRING	Specifies the max version of the APL runtime supported by the device. The Alexa.Presentation.APL 1.3 directives require implementation of the 1.6 version of the APL Core runtime, at a minimum. For more details, see APL Core runtime.

Because APL runtimes are backward-compatible, a content developer may still send APL documents declaring a version of APL greater than the maxVersion, but only the components and features of the maxRuntime are respected. For more details, see APL document version property.

The following table shows the minimum and maximum allowed runtime versions for maxVersion:

Min or Max?	Allowed versions
Minimum supported runtime version	1.6
Maximum supported runtime version	1.x

Context

RenderedDocumentState

Alexa expects a client to report RenderedDocumentState to communicate the current onscreen APL elements with each event that requires context. The presentationSession object helps Alexa to track the session Id from the device.

For more details, see Context and the APL Core Library repository and documentation.

Sample message

The following example shows the structure for a RenderedDocumentState context entry:


{
  "context": [
    {
      "header": {
        "namespace": "Alexa.Presentation.APL",
        "name": "RenderedDocumentState",
        "payloadVersion" : "1"
      },
      "payload": {
        "token": "token",
        "version" : "Alexa.Presentation.APL-1.1.x.x",
        "componentsVisibleOnScreen": [{
          "id": "list4050",
          "position": "100x200+30+50:1",
          "visibility": 1,
          "tags": {
            "focused": true,
            "list": {
              "itemCount": "2"
            }
          }
        }]
        "presentationSession": {
          "skillId": "MY_SKILL_ID",
          "id": "MY_ID"
         },
      }
    }
  ]
}

Context properties

Property	Type	Required?	Description
header.namespace	STRING	Yes	Namespace of the new state. Fixed value: `Alexa.Presentation.APL`
header.name	OBJECT	Yes	Name of the new state. Fixed value: `RenderedDocumentState`
header.payloadVersion	STRING	Yes	Payload version.
payload.componentsVisibleOnScreen	ARRAY OF OBJECTS	No	Container for the list of the visible components on screen. For more details, see APL Core Library repository and documentation.
payload.token	STRING	No	Id for the visual context captured in current event and sent originally by the skill. This value is the same as the `presentationToken` value reported by the original `RenderDocument` directive
payload.version	STRING	No	Version of the UI component on the device. Amazon recommends using some combination of `agentName` and `agentVersion` as defined in the APL Data-Binding Evaluation `Environment` object.
payload.presentationSession	OBJECT	Yes	A compound object to uniquely identify the presentation session.
payload.presentationSession.skillID	STRING	Yes	ID of skill that owns the presentation session.
presentationSession.id	STRING	Unique string identifying the instance of a skill.

Directives

RenderDocument

The RenderDocument directive renders a visually rich document by delivering a template document and data sources to a device. The presentationSession object tracks the session id to help with back navigation.

Message format

The following example shows the structure for a RenderDocument directive:


{
    "header": {
        "namespace": "Alexa.Presentation.APL",
        "name": "RenderDocument",
        "messageId": {{STRING}},
        "dialogRequestId": {{STRING}}
    },
    "payload": {
        "presentationToken": {{STRING}},
        "document": {{OBJECT}},
        "datasources": {{OBJECT}},
        "windowId": {{STRING}},
        "timeoutType": {{STRING}},
        "supportedViewports": {{ARRAY OF SUPPORTED VIEWPORTS}}
        "presentationSession": {
          "skillId": {{STRING}},
          "id": {{STRING}}
           "grantedExtensions": [
             {"uri" : {{JSON LIST}}}
            ],
           "autoInitializedExtensions": [
            {
              "uri" : {{STRING}},
              "settings": {{JSON OBJECT}}
            }
           ]
         },
    }
}

Payload parameters

The following table lists the payload parameters for the RenderDocument directive:

Payload Field	Type	Description
presentationToken	STRING	Unique identifier for the presentation.
document	OBJECT	APL document template for the device to use to structure a rendered presentation.
datasources	OBJECT	Data sources to bind to the rendered document.
windowId	STRING	Identifies which window to render the specified APL document.
timeoutType	STRING	Specifies the expected duration of the timeout of the document in the device and whether to persist the document in the background. Valid values are SHORT, TRANSIENT, and LONG. SHORT – 30 Seconds. The activity doesn't persist in the background. TRANSIENT – 10 Seconds. The activity doesn't persist in the background. LONG – No default timeout. The activity defines the task closure. The activity persists in the background if needed.
supportedViewports	ARRAY	Array of viewport specifications that the specified APL document supports. For more details about viewport support, see Select the Viewport Profiles Your Skill Supports.
presentationSession	OBJECT	A compound object to uniquely identify the presentation session.
presentationSession.skillId	STRING	ID of skill that owns the presentation session.
presentationSession.id	STRING	Unique string identifying the instance of a skill.
presentationSession.grantedExtensions	JSON LIST	List of extensions that are granted for use by this APL document. If the APL document requests an extension that is not part of `grantedExtensions` list, deny the extension. Use the format "uri" : "extension-uri".
presentationSession.autoInitializedExtensions	JSON LIST	List of extensions that are initialized in the APL runtime for this document. Use the format "settings": { "extension-setting-key":"extension-setting-value" }
presentationSession.autoInitializedExtensions.uri	STRING	URI of the extension to initialize.
presentationSession.autoInitializedExtensions.settings	STRING	Extension settings for initializing the extension on the device. This object is opaque to AVS and AVS passes the same properties that are specified in the manifest to the extension.

ExecuteCommands

The Alexa.Presentation.APL.ExecuteCommands directive runs an array of APL commands on APL documents that have been already rendered and share the same presentationToken.

Message format

The following code example shows the structure for a ExecuteCommands directive:


{
    "header": {
        "namespace": "Alexa.Presentation.APL",
        "name": "ExecuteCommands",
        "messageId": {{STRING}},
        "dialogRequestId": {{STRING}}
    },
    "payload": {
        "presentationToken": {{STRING}},
        "commands" : {{ARRAY OF COMMANDS}},
          ...
        ]
    }
}

Payload parameters

Although the commands themselves might vary, the following table lists the common properties that all commands share and that an ExecuteCommands array might include:

Property	Type	Required	Description
type	DIRECTIVE	Yes	Set to `Alexa.Presentation.APL.ExecuteCommands`.
presentationToken	STRING	Yes	String that tells the device about the `RenderDocument` command associated with the APL document for the commands.
commands	ARRRAY OF COMMANDS	Yes	Commands to run on the rendered APL document identified by the presentation token. Run each command in the array sequentially, rather than in parallel.

SendIndexListData

Alexa sends a SendIndexListData directive to devices with the item data requested by a LoadIndexListData event.

Message format

The following code example shows the structure for a SendIndexListData directive:


{
  "directive": {
    "header": {
      "namespace": "Alexa.Presentation.APL",
      "name": "SendIndexListData"
    },
    "payload": {
      "presentationToken": {{STRING}},
      "correlationToken": {{STRING}},
      "listId": {{STRING}},
      "listVersion": {{INTEGER}},
      "startIndex": {{INTEGER}},
      "minimumInclusiveIndex": {{INTEGER}},
      "maximumExclusiveIndex": {{INTEGER}},
      "items": {{ARRAY}}
    }
  }
}

Payload parameters

The following table lists the common properties that a SendIndexListData directive might include:

Field	Type	Required	Description
presentationToken	STRING	Yes	Presentation token supplied in the `LoadIndexListData` event.
correlationToken	STRING	No	Correlation token supplied in the `LoadIndexListData` event. `correlationToken` is mandatory if the skill is responding to a `LoadIndexListData` request. Alexa rejects skill responses if the expected `correlationToken` is not specified in a single `SendIndexListData` directive. Omit the `correlationToken` if the skill is proactively sending list items. Max-length: 1024 chars, case sensitive.
listId	STRING	Yes	Identifier of the list containing the items in this response. Only required if you don't specify a `correlationToken`; however, always including `listId` reduces overhead and helps with debugging. Max-length: 1024 chars, case sensitive.
listVersion	INTEGER	No	New version of the list following the update. Maintains list consistency between the skill and device. Lists should start at version 0, so the first `UpdateIndexListData` directive issued for a particular list should have a `listIndex` value of "1". The device buffers any `UpdateIndexListData` specifying an out-of-sequence `listVersion` until processing any missing or intermediate directives.
startIndex	INTEGER	Yes	Index of the first element in the items array. Required when a fast-scroll request exceeds available list locations. Valid range: -2³¹ → 2³¹-1 (incl.)
minimumInclusiveIndex	INTEGER	No	Index of the first item of the skill-managed array. When populated, this value replaces any specified value from a previous interaction. Continued absence of this property indicates that the minimum index is not yet known and further backwards scrolling is possible. If this value equals the index of the first item returned, no further backwards scrolling is possible. Valid range: -2³¹ → 2³¹-1, inclusive.
maximumExclusiveIndex	INTEGER	No	Last valid index of the skill-managed array, plus one. When populated, this value replaces any specified values in previous interactions. Continued absence of this property indicates that the maximum index is not yet known and further forwards scrolling is possible. If this value is greater than the index of the last item returned, no further forwards scrolling is possible. Valid range: -2³¹ → 2³¹-1, inclusive.
items	ARRAY	No	Array of objects to add to the device cache. Each item's encoding in the array has a max-length of 2048 chars.

UpdateIndexListData

The UpdateIndexListData directive communicates dynamic list changes to the device. The directive may include multiple changes, such as insert, set, and delete operations.

Message format

The following sample code shows the structure for a UpdateIndexListData directive:


{
  "directive": {
    "header": {
      "namespace": "Alexa.Presentation.APL",
      "name": "UpdateIndexListData"
    },
    "payload": {
      "presentationToken": {{STRING}},
      "listId": {{STRING}},
      "listVersion": {{INTEGER}},
      "operations": [
        {
          "type": InsertItem 
          "index": {{INTEGER}},
          "item": {{OBJECT}}
        },
        {
          "type": InsertMultipleItems
          "index": {{INTEGER}},
          "items": {{OBJECT ARRAY}}
        },
        {
          "type": SetItem
          "index": {{INTEGER}},
          "item": {{OBJECT}}
        },
        {
          "type": DeleteItem
          "index": {{INTEGER}}
        },
        {
          "type": DeleteMultipleItems
          "index": {{INTEGER}},
          "count": {{INTEGER}}
        }
        ...
      ]
    }
    }
  }
}

Payload parameters

The following table lists the common properties that a UpdateIndexListData directive might include:

Field	Type	Required	Description
presentationToken	STRING	Yes	String that tells the device about the `RenderDocument` command associated with the APL document for the list.
correlationToken	STRING	Yes	Identifier generated by a device to correlate requests with their corresponding directives. Max-length 1024 chars, case sensitive.
listId	STRING	Yes	Identifier for the list from the `RenderDocument` datasources with the items to update. Max-length: 1024 chars, case sensitive.
listVersion	INTEGER	Yes	The newest version of the list. Because all lists start at version 0, the first `UpdateIndexListData` directive issued for a particular list has a `listVersion` of 1. The device buffers a minimum of three `UpdateIndexListData` directives specifying an out-of-sequence `listVersion` until the device receives and processes any intermediate directives. Valid range: 1 → 2³¹-1.
operations	ARRAY	Yes	Individual operations apply to the list, in order. Complete each operation, including updating the index locations of list items, before processing the next operation in the array. Any operation processing errors should cause the device to discard later operations in the array and to discard further attempts to update the items in the target datasource. See the individual tables for each operation type.

InsertItem:

Field	Type	Required	Description
index	INTEGER	Yes	Index location in the existing list indicating where to insert the item. Increment the index for all existing list items after the new item by one. You can insert items at the end of the list, but you can't insert items at non-adjacent indexes. Valid range: -2³¹ → 2³¹-1.
item	OBJECT	Yes	Item data to include at the specified list index.

InsertMultipleItems:

Field	Type	Required	Description
index	INTEGER	Yes	Index in the existing list indicating the location to insert the first item. Insert the remaining items at sequentially increasing indexes. Increase the index for all existing list items at indexes after the insertion index by the length of the items array. You can insert items at the end of the list, but you can't insert items at non-adjacent indexes. Valid range: -2³¹ → 2³¹-1.
items	OBJECT ARRAY	Yes	The array of item data to include at the specified list index.

SetItem:

Field	Type	Required	Description
index	INTEGER	Yes	The index of the item to set or replace in the existing list. The definition and indexes of all other items in the list do not change. Attempting to set an item at an unpopulated index results in an error. Valid range: -2³¹ → 2³¹-1.
item	OBJECT	Yes	The new item data for the specified list index. Don't exceed 2048 characters for the JSON encoding of each item.

DeleteItem:

Field	Type	Required	Description
index	INTEGER	Yes	The index of the item to delete in the existing list. Decrease the index of all existing list items after the delete index. Attempting to delete an item at an unpopulated index results in an error. Valid range: -2³¹ → 2³¹-1.

DeleteMultipleItems:

Field	Type	Required	Description
index	INTEGER	Yes	Index of the first item to delete in the existing list. Perform subsequent deletions at sequentially increasing indexes. Decrease the index for all existing list items after the deleted items by the number of deletions. Attempting to delete an item at an unpopulated index results in an error. Valid range: -2³¹ → 2³¹-1.
count	INTEGER	Yes	Number of items at sequentially increasing indexes to delete. Valid range: 1 → 2³¹-1.

SendTokenListData

Alexa sends a SendTokenListData directive to devices with the items data requested by a LoadTokenListData event.

Message format

The following code example shows the structure for a SendTokenListData directive:


{
  "directive": {
    "header": {
      "namespace": "Alexa.Presentation.APL",
      "name": "SendTokenListData"
    },
    "payload": {
      "presentationToken": {{STRING}},
      "correlationToken": {{STRING}},
      "listId": {{STRING}},
      "pageToken": {{STRING}},
      "nextPageToken": {{STRING}},
      "items": {{ARRAY}}
    }
  }
}

Payload parameters

The following table lists the common properties that a SendTokenListData directive might include:

Field	Type	Required	Description
presentationToken	STRING	Yes	Presentation token supplied in the `LoadTokenListData` event.
correlationToken	STRING	No	Correlation token supplied in the `LoadTokenListData` event. `correlationToken` is mandatory if the skill is responding to a `LoadTokenListData` request. Alexa rejects skill responses if the expected `correlationToken` is not specified in a single `SendIndexListData` directive. Omit the `correlationToken` if the skill is proactively sending list items. Max-length: 1024 chars, case sensitive.
listId	STRING	Yes	Identifier of the list containing the items in this response. Only required if you don't specify a `correlationToken`; however, always including `listId` reduces overhead and helps with debugging. Max-length: 1024 chars, case sensitive.
pageToken	STRING	Yes	Opaque token for the array of items contained in the response. Max-length: 1024 chars, case sensitive.
nextPageToken	STRING	No	Opaque token to retrieve the next page of list items data in the direction indicated by the requested `pageToken`. If this property is absent, the last item in the list has been reached in the scroll direction. Max-length: 1024 chars, case sensitive.
items	ARRAY	No	Array of objects to add to the device cache. Each item's encoding in the array has a max-length of 2048 chars.

Events

LoadIndexListData

Send a LoadIndexListData event from the device to AVS to load more items into a dynamicIndexList.

Sample event message

The following example shows the structure for a LoadIndexListData event message:


{
  "event": {
    "header": {
      "namespace": "Alexa.Presentation.APL",
      "name": "LoadIndexListData"
    },
    "payload": {
      "presentationToken": "OPAQUE_TOKEN",
      "correlationToken": "CORRELATION_TOKEN"",
      "listId": "MY_LIST",
      "startIndex": 0,
      "count": 5
    }
  }
}

Payload parameters

The following table lists the payload parameters for the LoadIndexListData event.

Field	Type	Required	Description
presentationToken	STRING	Yes	Presentation token specified in the `RenderDocument` directive sent to the device.
correlationToken	STRING	Yes	Identifier generated by a device to correlate requests with their corresponding directives. Max-length 1024 chars, case sensitive.
listId	STRING	Yes	The identifier of the list whose items to fetch. Max-length 1024 chars, case sensitive.
startIndex	INTEGER	Yes	The lowest index of the items to fetch, inclusive. Valid range: -2³¹ → 2³¹-1 (incl.)
count	INTEGER	Yes	The number of items to fetch. Valid range: 1 - 1024. Examples: startIndex = 10, count = 2: Alexa should return items at indexes 10 and 11. startIndex = -2, count = 5: Alexa should return items at indexes -2, -1, 0, 1 and 2

LoadTokenListData

Send a LoadTokenListData event to load more items for a dynamicTokenList.

Sample event message

The following code example shows the structure for a LoadTokenListData event message:


{
  "event": {
    "header": {
      "namespace": "Alexa.Presentation.APL",
      "name": "LoadTokenListData"
    },
    "payload": {
      "presentationToken": "OPAQUE_TOKEN",
      "correlationToken": "CORRELATION_TOKEN"",
      "listId": "MY_LIST",
      "pageToken": "OPAQUE_TOKEN"
    }
  }
}

Payload parameters

The following table lists the payload parameters for the LoadTokenListData event.

Field	Type	Required	Description
presentationToken	STRING	Yes	Presentation token specified in the `RenderDocument` directive sent to the device.
correlationToken	STRING	Yes	Identifier generated by a device to correlate requests with their corresponding directives. Max-length 1024 chars, case sensitive.
listId	STRING	Yes	The identifier of the list whose items to fetch. Max-length 1024 chars, case sensitive.
pageToken	STRING	Yes	Opaque token of the array of items to fetch. The skill identifies whether the token represents a forward or backward scroll direction. Max-length 1024 chars, case sensitive.

UserEvent

Send an UserEvent event from the device directly to AVS when running a SendEvent command, such when a user presses a button.

The Alexa Skill that owns the APL document receives the event.Always send the UserEvent event along with a complete Context object. See Context for more details.

Sample event message

The following code example shows the structure for a UserEvent event message:


{
    "header": {
        "namespace": "Alexa.Presentation.APL",
        "name": "UserEvent",
        "messageId": "56fd9e9b-132c-4ebf-949e-e84e7a517c00"
    },
    "payload": {
        "presentationToken": "OPAQUE_TOKEN",
        "arguments": [
            "rideTypeSelected",
            2,
            "shared"
        ],
        "source": {
            "type": "Touchable",
            "handler": "onPress",
            "id": null,
            "value": null
        },
        "components": {
            "component1": "value1",
            "component2": 3
        }
    }
}

Payload parameters

The following table lists the payload parameters for the UserEvent event. The SendEvent command provides the source of the properties for UserEvent.

Field	Type	Description
presentationToken	STRING	Opaque token for the active presentation.
arguments	OBJECT	Array of argument data to pass to Alexa. For more details, see the APL Core Library repo and documentation.
source	OBJECT	Populate the source section of the payload with meta-information about the event trigger. For more details, see the APL Core Library repo and documentation.
components	OBJECT	The components property is a list of component IDs. Report the value of each of component in the event, which allows an Alexa developer to construct a form to directly send form contents to the server. For more details, see the APL Core Library repo and documentation.

RuntimeError

Send a RuntimeError event to notify a skill about any errors that occurred during APL processing. This request is for notification only. Skills can't return a response to a RuntimeError request.

Sample event message

The following sample code shows the structure for a RuntimeError event message:


{
  "header": {
    "namespace": "Alexa.Presentation.APL",
    "name": "RuntimeError",
  },
  "payload": {
    "presentationToken": {{STRING}},
    "errors": [
      {
        "type": "LIST_ERROR",          // Required.
        "reason": {{STRING}},          // Required. Type of error
        "listId": {{STRING}},          // Required. Field is specific to the LIST_ERROR type.
        "listVersion": {{INTEGER}},    // Optional. Field is specific to the LIST_ERROR type.
        "operationIndex": {{INTEGER}}, // Optional. Field is specific to the LIST_ERROR type. The index of the operation which caused the error (when known)
        "message": {{STRING}},         // Required. See examples for each error condition in the table above.
      }
    ]
  }
}

Payload parameters

The following table lists the payload parameters for the RuntimeError event.

Field	Type	Required	Description
presentationToken	STRING	Yes	Presentation token that identifies the APL experience.
errors	ARRAY	Yes	An array of reported errors.
error.type	ENUM	Yes	Error type indicator. Current valid value is 'LIST_ERROR'.
error.reason	STRING	Yes	Describes the type of error which occurred. The following values are valid: DUPLICATE_LIST_VERSION DUPLICATE_PAGE_TOKEN INCONSISTENT_LIST_ID INCONSISTENT_PAGE_ITEMS INCONSISTENT_PAGE_TOKEN INCONSISTENT_RANGE INVALID_DATASOURCE INVALID_LIST_ID INTERNAL_ERROR (unexpected platform/device issues) INVALID_OPERATION INVALID_PRESENTATION_TOKEN LIST_INDEX_OUT_OF_RANGE LOAD_INDEX_OUT_OF_RANGE LOAD_TIMEOUT MISSING_LIST_ITEMS MISSING_LIST_VERSION MISSING_LIST_VERSION_IN_SEND_DATA OCCUPIED_LIST_INDEX
error.listId	STRING	Yes	Specific to the LIST_ERROR error type. Contains the identifier of the list which encountered the error.
error.listVersion	INTEGER	No	Specific to the LIST_ERROR error type. Contains the `listVersion` specified by the update that encountered the error, if known.
error.operationIndex	INTEGER	No	Specific to the LIST_ERROR error type. Contains the index of the operation that caused the error, if known.
error.message	STRING	Yes	Text description of the error.

Alexa Multi-Modal API Overview
APL Extensions
Alexa.Presentation reference
Alexa.Presentation.APL.Video reference
APL Core Library repository and documentation

Alexa.Presentation.APL 1.3

Version changes

Capability assertion

About APL runtime versions

Context

RenderedDocumentState

Directives

RenderDocument

ExecuteCommands

SendIndexListData

UpdateIndexListData

SendTokenListData

Events

LoadIndexListData

LoadTokenListData

UserEvent

RuntimeError

Related topics