Alexa.Presentation.APL 1.3

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

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: -231 → 231-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: -231 → 231-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: -231 → 231-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 → 231-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: -231 → 231-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: -231 → 231-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: -231 → 231-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: -231 → 231-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: -231 → 231-1.
count INTEGER Yes Number of items at sequentially increasing indexes to delete. Valid range: 1 → 231-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: -231 → 231-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.
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment