Alexa.Presentation.APL Interface Reference


The Alexa.Presentation.APL interface provides directives and requests that display content on a device with a screen, such as an Echo Show. You use directives in requests in this interface to display a standard APL response on a device with a screen, and to communicate with a widget installed on the device.

Alexa.Presentation.APL in supportedInterfaces

When the user's device has a screen that supports APL, the context.System.device.supportedInterfaces object includes [Alexa.Presentation.APL]:

Always check supportedInterfaces before returning the Alexa.Presentation.APL directives. For an example that does this with the ASK SDK, see Make sure the user's device supports APL in Use Alexa Presentation Language with the ASK SDK v2.

Available Extensions in context

Extensions are optional enhancements that provide additional APL functionality. For some extensions, you must request the extension in the in the skill manifest. When the user's device supports these extensions, the context object includes an Extensions.available property. This property contains a map in which the key for each item is the URI for the available extension.

The following example illustrates a request from a device that supports the smart-motion and entity-sensing extensions.

{
  "version": "1.0",
  "session": {},
  "context": {
    "AudioPlayer": {
      "playerActivity": "IDLE"
    },
    "Viewports": [
      {
        "type": "APL",
        "id": "<string>"
      }
    ],
    "Extensions": {
      "available": {
        "alexaext:smartmotion:10": {},
        "alexaext:entitysensing:10": {}
      }
    }
  }
}

The context.Extensions property includes extensions that meet both the following criteria:

  • You requested the extension in the skill manifest in the requestedExtensions property.

    For details about how to request extensions in the manifest, see Request an extension in the skill manifest.

  • The device supports the extension.

Not all extensions can be included in the manifest. See the topic for the extension you want to use to determine the extension's requirements.

Directives

The following table lists the directives available in the Alexa.Presentation.APL interface. The "Widget support" column indicates whether you can use the directive to communicate with a widget installed on the device.

Directive description Widget support

RenderDocument

Instructs the device to display the APL content provided in the specified document. You can also optionally provide one or more datasources to bind content to document.

No

ExecuteCommands

Instructs the device to run the provided commands on one of the following:

  • Standard document – The currently rendered document identified by the token.
  • Widget – The installed widget identified by the presentationUri.

Yes

SendIndexListData

Sends a new set of list items to display, in response to a LoadIndexListData request. Include a dynamicIndexList data source with the next set of items to display. Don't include outputSpeech or shouldEndSession in your response.

No

SendTokenListData

Sends a new page of list items to display, in response to a LoadTokenListData request . Include a dynamicTokenList data source with the next page of items to display. Don't include outputSpeech or shouldEndSession in your response.

No

UpdateIndexListData

Send a set of data operations to Alexa to insert, set, and delete list items in a data source that has already been sent to the device in a RenderDocument directive. You can include multiple changes in a single directive.

No

RenderDocument directive

Instructs the device to display the APL content provided in the specified document. You can also optionally provide one or more datasources to bind content to document.

The following RenderDocument example sends a document with two Text components and a data source called helloworldData.

{
  "type": "Alexa.Presentation.APL.RenderDocument",
  "token": "helloworldToken",
  "document": {
    "type": "APL",
    "version": "2024.2",
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": [
        {
          "type": "Container",
          "height": "100%",
          "width": "100%",
          "items": [
            {
              "type": "Text",
              "id": "helloTextComponent",
              "text": "${payload.helloworldData.properties.helloText}",
              "textAlign": "center",
              "textAlignVertical": "center",
              "maxLines": 3,
              "grow": 1
            },
            {
              "type": "Text",
              "id": "newHelloTextComponent",
              "text": "${payload.helloworldData.properties.newHelloText}",
              "textAlign": "center",
              "textAlignVertical": "bottom",
              "maxLines": 3,
              "opacity": 0
            }
          ]
        }
      ]
    }
  },
  "datasources": {
    "helloworldData": {
      "type": "object",
      "objectId": "helloworld",
      "properties": {
        "helloText": "Hello world! This APL document displays text from a datasource called helloworldData.",
        "newHelloText": "I hid the original hello text and then displayed this!"
      }
    }
  }
}

You can also save your document with your skill in the developer console and then provide a link to it in the RenderDocument directive. The following example assumes that "hello world" document has been saved with the name "helloworld-by-link".

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.RenderDocument",
      "token": "helloworldToken",
      "document": {
        "src": "doc://alexa/apl/documents/helloworld-by-link",
        "type": "Link"
      },
      "datasources": {
        "helloworldData": {
          "type": "object",
          "objectId": "helloworld",
          "properties": {
            "helloText": "Hello world! This APL document displays text from a datasource called helloworldData.",
            "newHelloText": "I hid the original hello text and then displayed this!"
          }
        }
      }
    }
  ]
}

RenderDocument properties

Property Type Required Description

type

String

Yes

Set to Alexa.Presentation.APL.RenderDocument

token

String

Yes

String that identifies the document. You use this when you issue subsequent directives that refer to the document. For example, you need this token when you send the ExecuteCommands directive.

document

Object

Yes

An object representing the APL document to send to the device.

When document.type is "APL", document must contain the complete JSON document.

When document.type is "Link", document must contain the src property with the reference to the document.

document.type

One of: APL, Link

Yes

Indicates the type of document to send. Set to "APL" when document contains the full document object. Set to "Link" when document.src contains a document link.

document.src

URL

When document.type is Link

The URL that identifies the document saved in the developer console. For APL, the link has the following syntax: doc://alexa/apl/documents/<document-name>. Replace <document-name> with the name you used when saving the document. Don't include this property when document.type is APL.

sources

Map of additional documents or references to documents

No

An object containing named APLA documents or links. These documents can be referenced by the "template" parameter in the aplAudioToSpeech transformer.

datasources

Map of data source objects

No

Object that can contain other objects that you can use to bind data to the APL document.

The document property must always contain either the src property set to the URL for a document, or the JSON for the full document.

For an example showing how you would send RenderDocument with the ASK SDK v2, see Return RenderDocument in your request handler response in Use Alexa Presentation Language with the ASK SDK v2.

Link to an APL document saved in the developer console

You can save an APL document in the developer console and then use a link to that document in the RenderDocument directive. This means you don't need to export the JSON for your APL document and copy it into your code.

A link to a document in the developer console has the following syntax:

doc://alexa/apl/documents/<document-name>

The <document-name> is the name you used when saving the document in the developer console.

For details about building and saving a document in the developer console, see Build Documents in the Developer Console.

You can use the Integrate with skill option in the developer console to copy a code snippet with a link to the document in the required format.

  1. In the developer console, open the skill.
  2. In the left-hand navigation, click Multimodal Responses.
  3. Find the document you want to integrate and click Integrate with skill.
  4. Review the sample code and copy to your skill code as needed.

RenderDocument and other skill directives

  • Your response can combine RenderDocument with any of the of the Dialog directives except for Dialog.Delegate. For example, you can use Dialog.ElicitSlot to ask the user for a slot value, and at the same time display information related to that slot on the screen with RenderDocument.
  • Your response cannot combine RenderDocument with directives from the following interfaces:
    • AudioPlayer
    • Display
    • VideoApp

ExecuteCommands directive

Instructs the device to run the provided commands on one of the following:

  • Standard document – The currently rendered document identified by the token.
  • Widget – The installed widget identified by the presentationUri.

The following example sends an ExecuteCommands directive that acts on the document identified with the token helloworldToken. This directive has two commands:

  • The first AnimateItem command changes the opacity of the component helloTextComponent to 0 over 3 seconds to make it fade from view.
  • The second AnimateItem command changes the opacity of the component newHelloTextComponent from 0 to 1 over 3 seconds to make it fade into view.
{
  "type": "Alexa.Presentation.APL.ExecuteCommands",
  "token": "helloworldToken",
  "commands": [
    {
      "type": "AnimateItem",
      "componentId": "helloTextComponent",
      "duration": "3000",
      "easing": "linear",
      "value": [
        {
          "property": "opacity",
          "to": "0.0"
        }
      ]
    },
    {
      "type": "AnimateItem",
      "componentId": "newHelloTextComponent",
      "duration": "3000",
      "easing": "linear",
      "value": [
        {
          "property": "opacity",
          "to": "1.0"
        }
      ]
    }
  ]
}

The following example shows the directives array for a response with the ExecuteCommands directive targeting a widget.

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.ExecuteCommands",
      "presentationUri": "widget://amzn1.ask.skill.1/MyWidgetSandbox/f1cf2427-1-1-1-1",
      "commands": [
        {
          "type": "AnimateItem",
          "duration": 1000,
          "componentId": "itemDescription",
          "value": {
            "property": "opacity",
            "to": 0
          }
        },
        {
          "type": "SetValue",
          "componentId": "successMessage",
          "property": "text",
          "value": "Item Saved!"
        }
      ]
    }
  ]
}

Widgets support most standard APL commands. For the list of commands that you can send using ExecuteCommands, see Standard Commands.

ExecuteCommands properties

Property Type Required Description

type

String

Yes

Set to Alexa.Presentation.APL.ExecuteCommands

token

String

No

A string that identifies the RenderDocument command used to display the document these commands apply to. Required when the ExecuteCommands directive targets a standard APL document displayed with RenderDocument. Not used when the directive targets a widget.

presentationUri

string

No

A string that identifies the widget to target with the commands. For a user interaction with your widget, such as a tap event, you can get the presentationUri for the widget from the UserEvent request. For a standard voice request when your widget is in view, you can get the presentationUri from the widget visual context.

commands

Array of commands

Yes

Commands to run on the rendered document identified by the token. The array of commands behaves like an implicit Sequential command. That is, the commands run one after the other rather than in parallel.

The ExecuteCommands directive targets the commands against the specific document identified with the token or presentationUri

  • To target a standard document, the token you provide must match the token you provided with the RenderDocument directive that sent the corresponding document.
  • To target a widget, the presentationUri must match the identifier for a widget installed on the device.

You can send the RenderDocument and ExecuteCommands directives in the same skill response, or separate responses:

  • When your response includes both directives, the device displays the specified document first, then runs the commands, provided the token matches in both directives.
  • When you return ExecuteCommands in a separate response, the device runs the commands against the document currently displayed on the viewport. The token must match the token used in the earlier RenderDocument directive.

    Before you send ExecuteCommands in this scenario, check the visual context in the request to confirm that the document is currently displayed. You can get the token for the currently displayed document from the context.["Alexa.Presentation.APL"].token property in the request.

In both cases, if the token values do not match between the directives, the commands don't run.

The following example request shows that the viewport is currently displaying the document with the token helloworldWithButtonToken (for brevity, some parts of this request are omitted).

{
  "version": "1.0",
  "session": {},
  "context": {
    "Alexa.Presentation.APL": {
      "token": "helloworldWithButtonToken",
      "version": "APL_WEB_RENDERER_GANDALF",
      "componentsVisibleOnScreen": [
        {
          "uid": ":1000",
          "position": "1024x600+0+0:0",
          "type": "text",
          "tags": {
            "viewport": {}
          },
          "children": [
            {
              "id": "fadeHelloTextButton",
              "uid": ":1002",
              "position": "270x70+377+450:0",
              "type": "text",
              "tags": {
                "focused": false,
                "clickable": true
              },
              "entities": []
            }
          ],
          "entities": []
        }
      ]
    },
    "System": {},
    "Viewport": {},
    "Viewports": []
  },
  "request": {}
}

For an example that shows how you check for this property and return ExecuteCommands with the ASK SDK, see Return ExecuteCommands in a request handler response in Use Alexa Presentation Language with the ASK SDK v2.

ExecuteCommands and other skill directives

Your response cannot combine ExecuteCommands with directives from the following interfaces:

  • AudioPlayer
  • Dialog
  • Display
  • VideoApp

SendIndexListData directive

Sends a new set of list items to display, in response to a LoadIndexListData request. Include a dynamicIndexList data source with the next set of items to display. Don't include outputSpeech or shouldEndSession in your response.

Property Type Required Description

type

Directive

Yes

Set to Alexa.Presentation.APL.SendIndexListData

correlationToken

String

Yes, when sent in response to a LoadIndexListData

The correlation token supplied in the LoadIndexListData request. Required when sent in response to a LoadIndexListData. Can be omitted otherwise. See Proactive loading.

listId

String

Yes

The identifier for the list to update with this response.

listVersion

Integer

No

The new version number for the list following the update, used to maintain list consistency between the skill and the device. Required when you also use UpdateIndexListData to update the same list, otherwise not required.

startIndex

Integer

Yes

Index of the first element in the items array.

minimumInclusiveIndex

String

No

The index of the first item in the array. When populated, this value replaces any value specified in a previous interaction. Absence of this property indicates that the minimum index is not yet known and Alexa continues requesting more items as the user scrolls backwards (the list is a backward-scrolling list). When equal to the index of the first item returned, no further backwards scrolling is possible and Alexa stops requesting more items.

maximumExclusiveIndex

String

No

The last valid index of the array plus one. When populated, this value replaces any value specified in a previous interaction. Absence of this property indicates that the maximum index is not yet known and Alexa continues requesting more items as the user scrolls forwards (the list is a forward-scrolling list). When this property is one more than the index of the last item returned then no further forward scrolling is possible and Alexa stops requesting more items.

items

Array

No

Array of objects to add to the list.

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.SendIndexListData",
      "correlationToken": "alexa-provided-correlation-token",
      "listId": "my-list-id",
      "listVersion": 3,
      "startIndex": 11,
      "minimumInclusiveIndex": 11,
      "maximumExclusiveIndex": 21,
      "items": [
        {"primaryText":"item 11"},
        {"primaryText":"item 12"},
        {"primaryText":"item 13"},
        {"primaryText":"item 14"},
        {"primaryText":"item 15"},
        {"primaryText":"item 16"},
        {"primaryText":"item 17"},
        {"primaryText":"item 18"},
        {"primaryText":"item 19"},
        {"primaryText":"item 20"}
      ]
    }
  ]
}

Proactive loading

You must provide the correlationToken when your skill responds to a LoadIndexListData request. Alexa rejects the skill response if the expected correlationToken is not specified in exactly one SendIndexListData directive.

Omit the correlationToken when you send a set of list items not in response to a LoadIndexListData request.

SendTokenListData directive

Sends a new page of list items to display, in response to a LoadTokenListData request . Include a dynamicTokenList data source with the next page of items to display. Don't include outputSpeech or shouldEndSession in your response.

Property Type Required Description

type

Directive

Yes

Set to "Alexa.Presentation.APL.SendTokenListData"

correlationToken

String

No

The correlation token supplied in the LoadTokenListData request. Required when sent in response to a LoadTokenListData. Can be omitted otherwise. See Proactive loading.

listId

String

Yes

The identifier of the list whose items are contained in this response.

pageToken

String

Yes

Opaque token for the array of items which are contained in this response.

nextPageToken

String

No

Opaque token to retrieve the next page of list items data, in the scroll direction indicated by the requested pageToken). Absence of this property indicates that the last item in the list has been reached in the scroll direction, i.e. no further scrolling is possible in this direction.

items

Array

No

Array of objects to be added to the list.

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.SendTokenListData",
      "token": "developer-provided-token",
      "correlationToken": "alexa-provided-correlation-token",
      "listId": "my-list-id",
      "pageToken": "myListPage2",
      "nextPageToken" "myListPage3"
      "items": [
        {"primaryText":"item 11"},
        {"primaryText":"item 12"},
        {"primaryText":"item 13"},
        {"primaryText":"item 14"},
        {"primaryText":"item 15"},
        {"primaryText":"item 16"},
        {"primaryText":"item 17"},
        {"primaryText":"item 18"},
        {"primaryText":"item 19"},
        {"primaryText":"item 20"}
      ]
    }
  ]
}

Proactive loading

You must provide the correlationToken when your skill responds to a LoadTokenListData request. Alexa rejects the skill response if the expected correlationToken is not specified in exactly one SendTokenListData directive.

Omit the correlationToken when you send a set of list items not in response to a LoadTokenListData request.

UpdateIndexListData directive

Send a set of data operations to Alexa to insert, set, and delete list items in a data source that has already been sent to the device in a RenderDocument directive. You can include multiple changes in a single directive.

Property Type Required Description

type

Directive

Yes

Set to Alexa.Presentation.APL.UpdateIndexListData

token

String

Yes

The presentation token specified in the RenderDocument directive sent to Alexa.

listId

String

Yes

The identifier for the list to update with this response.

listVersion

Integer

Yes

The new version of the list following the update, used to maintain list consistency between the skill and Alexa.

operations

Array

Yes

Individual operations to apply to the list, in array order. Alexa applies each item in it's entirety before processing the next operation in the array. Fully applying an operation includes making the change and updating the index locations of surrounding items. If a failure occurs when processing an operation, Alexa discards later operations in the array and discards further directives which attempt to update the items in the target datasource.

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.UpdateIndexListData",
      "token": "developer-provided-token",
      "listId": "my-list-id",
      "listVersion": 3,
      "operations": [
        {
          "type": "InsertItem",
          "index": 10,
          "item": {
            "primaryText": "new item 9.5, inserted before item 10"
          }
        },
        {
          "type": "InsertMultipleItems",
          "index": 12,
          "items": [
            {"primaryText":"first of three new items, inserted before item 12"},
            {"primaryText":"second of three"},
            {"primaryText":"third of three"}
          ]
        },
        {
          "type": "SetItem",
          "index": 14,
          "item": {"primaryText":"Replacement text for item 14"}
        },
        {
          "type": "DeleteItem",
          "index": 16
        },
        {
          "type": "DeleteMultipleItems",
          "index": 17,
          "count": 2
        }
      ]
    }
  ]
}

listVersion

The new version of the list following the update, used to maintain list consistency between the skill and Alexa. Alexa assumes all lists start at version 0, so the first UpdateIndexListData directive issued for a particular list sets listIndex to 1. Alexa buffers any UpdateIndexListData directives specifying an out-of-sequence listVersion until the missing or intermediate directives are received and processed.

This field is required for UpdateIndexListData but optional for SendIndexListData in some cases:

  • When you don't do any insert, set, or delete updates on the list, you don't need to populate this value.
  • When you do perform insert, set, or delete operations on the list, you must populate this value for all SendIndexListData directives.

Therefore, for a particular list, Alexa discards the following:

  • All UpdateIndexListData directives received after a SendIndexListData directive which didn't specify a listVersion.
  • All SendIndexListData directives that don't specify a listVersion after receipt of a UpdateIndexListData directive.

operations

Enumeration of possible update operations.

InsertItem

Inserts a single item into the data source at the specified index.

You can insert items within the range of the list or add the items to the end of the list. Attempts to insert items at non-adjacent indexes results in an error. For example, if the current indexes range from M to N, you can insert items into in the range M to N+1.

Field Type Required Description

index

Integer

Yes

The index at which to insert the item in the existing list. All existing list items at indexes greater or equal to the insert index increase by one. If defined, the value of maximumExclusiveIndex in the data source also increases by one.

item

Object

Yes

The item data to include at the specified list index.

For example, the initial data source had 10 items with indexes 0-9. An InsertItem operation with index set to 5 does the following:

  • Inserts the new item at position 5.
  • Updates the index for the existing items 5-9 to 6-10. The original item 5 becomes 6, the original 6 becomes 7, and so on.
  • Updates the maximumExclusiveIndex property for the data source from 10 to 11.

InsertMultipleItems

Inserts an array of items at the specified index.

You can insert items within the range of the list or add the items to the end of the list. Attempts to insert items at non-adjacent indexes results in an error. For example, if the current indexes range from M to N, you can insert items into in the range M to N+1.

Field Type Required Description

index

Integer

Yes

The index at which to insert the first of the specified items in the existing list, with the rest of the items inserted at sequentially increasing indexes. All existing list items at indexes greater or equal to the insert index increase by the length of the items array. If defined, the value of maximumExclusiveIndex in the data source also increases by the items array length.

items

Array

Yes

The array of item data to include at the specified list index.

For example, the initial data source had 10 items with indexes 0-9. An InsertMultipleItem operation with index set to 5 and 2 new items in items does the following:

  • Inserts the two new items at positions 5 and 6.
  • Adds 2 to the index for the original items 5-9. The original item 5 becomes 7, the original item 6 becomes item 8, and so on.
  • Updates the maximumExclusiveIndex property for the data source from 10 to 12.

SetItem

Replace the item at the specified index with the provided item.

Field Type Required Description

index

Integer

Yes

The index of the item to replace in the existing list. The definition and indexes of all other items in the list are unchanged. An attempt to set an item at an unpopulated index results in an error.

item

Object

Yes

The new item data for the specified list index.

For example, the initial data source had 10 items with indexes 0-9. A SetItem operation with index set to 5 does the following:

  • Replaces the existing item at position 5 with the new item.

DeleteItem

Delete the item at the specified index.

Field Type Required Description

index

Integer

Yes

The index of the item to delete in the existing list. All existing list items at indexes greater than the delete index decrease by one. If defined, the value of maximumExclusiveIndex in the data source also decreases by one. Any attempt to delete an item at an unpopulated index results in an error.

For example, the initial data source had 10 items with indexes 0-9. A DeleteItem operation with index set to 5 does the following:

  • Deletes the existing item at position 5.
  • Updates the index for the existing items 6-9 to 5-8. The original item 6 becomes 5, the original item 7 becomes 6, and so on.
  • Updates the maximumExclusiveIndex property for the data source from 10 to 9.

DeleteMultipleItems

Delete the specified count of items from the data source, beginning at the specified index.

Field Type Required Description

index

Integer

Yes

The index of the first item to delete in the existing list, with the rest of the items deleted at sequentially increasing indexes. All existing list items at indexes greater than those which have are deleted decrease their index by the count. If defined, the value of maximumExclusiveIndex also decreases by the count. Any attempt to delete an item at an unpopulated index results in an error.

count

Integer

Yes

The number of items at sequentially increasing indexes to delete.

For example, the initial data source had 10 items with indexes 0-9. A DeleteMultipleItems operation with index set to 5 and count set to 2 does the following:

  • Deletes the original items at positions 5 and 6.
  • Subtracts 2 from the index for the original items 7-9. The original item 7 gets a new index of 5, the original item 8 becomes item 6, and and the original item 9 becomes 7.
  • Updates the maximumExclusiveIndex property for the data source from 10 to 8.

Requests

The following table lists the requests available in the Alexa.Presentation.APL interface. The "Widget support" column indicates whether Alexa sends the request to your skill from a widget installed on the device.

Request Description Widget support

LoadIndexListData

Alexa sends your skill a LoadIndexListData request to ask for more list items for a dynamicIndexList data source. For example, your skill gets this request when the user scrolls near the end of the previously-loaded items.

No

LoadTokenListData

Alexa sends your skill a LoadTokenListData request to ask for the next page of items for a dynamicTokenList data source. For example, your skill gets this request when the user scrolls near the end of the previously-loaded page of items.

No

RuntimeError

Sent to notify the skill about any errors that happened during APL processing. This request is for notification only. The skill can't return a response to a RuntimeError request.

No

UserEvent

Alexa sends your skill an Alexa.Presentation.APL.UserEvent request when an event on the device triggers the SendEvent command. This lets your skill service receive messages in response to the user's actions on the device.

For a widget, the request includes the presentationUri. You can use identifier to target the widget with the ExecuteCommands directive. The valid responses your skill can return from this request depend on the type of interaction mode you configure in the SendEvent command. For details, see Interaction mode.

Yes

LoadIndexListData request

Alexa sends your skill a LoadIndexListData request to ask for more list items for a dynamicIndexList data source. For example, your skill gets this request when the user scrolls near the end of the previously-loaded items.

Property Type Required Description

type

String

Yes

Set to Alexa.Presentation.APL.LoadIndexListData

token

String

Yes

The presentation token specified in the RenderDocument directive sent to Alexa.

correlationToken

String

Yes

An Alexa-generated identifier used to correlate requests with their corresponding response directives. Include this when you respond with a SendIndexListData directive.

listId

String

Yes

The identifier of the list for which to fetch items.

startIndex

String

Yes

The lowest index of the items to fetch (inclusive)

count

Integer

Yes

The number of items to fetch.

{
  "request": {
    "type": "Alexa.Presentation.APL.LoadIndexListData",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2020-03-12T19:47:02Z",
    "locale": "en-US",
    "token": "developer-provided-token",
    "correlationToken": "101",
    "listId": "my-list-id",
    "startIndex": 20,
    "count": 10
  }
}

Valid responses

You can respond to a LoadIndexListData request with a SendIndexListData directive.

LoadTokenListData request

Alexa sends your skill a LoadTokenListData request to ask for the next page of items for a dynamicTokenList data source. For example, your skill gets this request when the user scrolls near the end of the previously-loaded page of items.

Property Type Required Description

type

String

Yes

Set to Alexa.Presentation.APL.LoadTokenListData

token

String

Yes

The presentation token specified in the RenderDocument directive you sent to Alexa.

correlationToken

String

Yes

An Alexa-generated identifier used to correlate requests with their corresponding response directives. Include this when you respond with a SendTokenListData directive.

listId

String

Yes

The identifier of the list for which to fetch items.

pageToken

String

Yes

A token associated with the items to fetch. You determine the string to use for the pageToken. Your skill must keep track of the data associated with the token and be able to determine whether the token represents a forward or backward scroll direction.

{
  "request": {
    "type": "Alexa.Presentation.APL.LoadTokenListData",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2021-03-12T19:47:02Z",
    "locale": "en-US",
    "token": "developer-provided-token",
    "correlationToken": "101",
    "listId": "my-list-id",
    "pageToken": "myListPage2"
  }
}

Valid responses

You can respond to a LoadTokenListData request with a SendTokenListData directive.

RuntimeError request

Sent to notify the skill about any errors that happened during APL processing. This request is for notification only. The skill can't return a response to a RuntimeError request.

Property Type Required Description

type

String

Yes

Set to Alexa.Presentation.APL.RuntimeError

token

String

No

The presentation token specified in the RenderDocument directive sent to Alexa.

errors

Array

Yes

An array of reported errors.

{
  "type": "Alexa.Presentation.APL.RuntimeError",
  "token": "developer-provided-token",
  "errors": [
    {
      "type": "LIST_ERROR",
      "reason": "LIST_INDEX_OUT_OF_RANGE",
      "listId": "my-list-id",
      "listVersion": 3,
      "operationIndex": 3,
      "message": ""
    }
  ]
}

errors

Property Type Required Description

type

String

Yes

Polymorphic error type indicator.

reason

String

Yes

Describes the reason for the error that occurred.

message

String

Yes

A human-readable description of the error.

type

Polymorphic error type indicator. Each error type can have type-specific parameters.

Property Description

LIST_ERROR

Errors related to processing a dynamicIndexList data source.

reason

Error type specific failure reasons. Generic values available for any type:

  • INTERNAL_ERROR – unexpected issue in the Alexa service.
LIST_ERROR

For possible reasons see: Error cases.

Field Type Required Description

listId

String

Yes

Contains the identifier of the list which encountered the error.

listVersion

String

No

Contains the listVersion specified by the update which encountered the error (when known)

operationIndex

Integer

No

Contains the index of the operation which caused the error (when known)

UserEvent request

Alexa sends your skill an Alexa.Presentation.APL.UserEvent request when an event on the device triggers the SendEvent command. This lets your skill service receive messages in response to the user's actions on the device. You can use event handlers on components in your document to trigger SendEvent. For example, the TouchWrapper component has an onPress event handler. You can set this handler to the SendEvent command to get a UserEvent request when a user touches the component on the viewport.

The UserEvent request includes information about the component and the event that triggered the SendEvent command. When you define SendEvent in a component's event handler, you can specify the information you want to get in the corresponding UserEvent request. Use this in your event handler in your code.

UserEvent properties

Property Type Description

type

String

Always set to Alexa.Presentation.APL.UserEvent

token

String

Token provided with the RenderDocument or ExecuteCommands directive that sent this UserEvent. For a widget, token contains a generated token.

arguments

Array of values

Array of values specified in the arguments property of the SendEvent command that triggered this request.

source

Object

Information about the APL component and event handler (if applicable) that was the source of this event.

components

Object

Value of each component identified in the components property of the SendEvent command that triggered this request.

presentationUri

String

Applies to widgets. A generated token that identifies the widget. Use this value to identify the widget if you respond with ExecuteCommands.

Standard APL document UserEvent request example

The following example shows part of an APL document that sends an event to a skill when the user presses one of the TouchWrapper components rendered by the Sequence component via touch or a d-pad on a remote control.

{
  "type": "Sequence",
  "id": "myCustomSequence",
  "height": "100vh",
  "data": "${payload.templateData.properties.animalList}",
  "numbered": true,
  "item": {
    "type": "TouchWrapper",
    "id": "animalListTouchWrapper",
    "item": {
      "type": "Text",
      "text": "${data.textToShow}"
    },
    "onPress": [
      {
        "type": "SendEvent",
        "arguments": [
          "listItemPressed",
          "${ordinal}",
          "${data.dataToSend}"
        ]
      }
    ]
  }
}

The Sequence uses a data source called templateData to display a series of items in the Sequence and define the data to include in the UserEvent. The following example illustrates this data source.

{
  "templateData": {
    "properties": {
      "animalList": [
        {
          "textToShow": "Aardvark",
          "dataToSend": "animalKey123"
        },
        {
          "textToShow": "Aardwolf",
          "dataToSend": "animalKey124"
        },
        {
          "textToShow": "Baboon",
          "dataToSend": "animalKey202"
        }
      ]
    }
  }
}

In the above example, the arguments array for the SendEvent command specifies three items:

  • The static text "listItemPressed"
  • The ordinal property from the data-binding context. This property is available since the TouchWrapper is a child component of a Sequence.
  • The value of the item's dataToSend property, from the data source.

Therefore, when the user selects the second item ("Aardwolf"), the skill gets a UserEvent request that looks like the following.

{
  "version": "1.0",
  "session": {},
  "context": {},
  "request": {
    "type": "Alexa.Presentation.APL.UserEvent",
    "requestId": "amzn1.echo-api.request.1",
    "token": "token-provided-with-RenderDocument",
    "timestamp": "2020-01-17T16:48:11Z",
    "locale": "en-US",
    "arguments": [
      "listItemPressed",
      2,
      "animalKey124"
    ],
    "components": {},
    "source": {
      "type": "TouchWrapper",
      "handler": "Press",
      "id": "animalListTouchWrapper"
    },
  }
}

Widget UserEvent request example

The following example shows a UserEvent request sent by a widget. The request includes a generated token and presentationUri.

{
  "request": {
    "type": "Alexa.Presentation.APL.UserEvent",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2022-04-07T21:51:19Z",
    "locale": "en-US",
    "arguments": [
      {
        "itemId": "ItemIDForSmokedWildSalmon"
      }
    ],
    "components": {},
    "source": {
      "type": "TouchWrapper",
      "handler": "Press",
      "id": "saveItemButton",
      "value": false
    },
    "token": "f1cf2427-1-1-1-1",
    "presentationUri": "widget://amzn1.ask.skill.1_development/MyWidgetSandbox/f1cf2427-1-1-1-1"
  }
}

Get component data in the UserEvent

In addition to the data provided in the source and arguments properties, you can also get information about other components displayed on the viewport. To do this, assign each component an identifier with the id property. Then include the id for each component you want in the components array in your SendEvent command.

For example, each component has a checked state that can be true or false. You can use the SetValue command to change the checked state in response to user interaction. The following AlexaButton example toggles the checked state and changes the button text when the user selects the button.

{
  "type": "AlexaButton",
  "id": "idForTheToggleButton",
  "buttonText": "Toggle button: false",
  "primaryAction": [
    {
      "type": "SetValue",
      "componentId": "idForTheToggleButton",
      "property": "checked",
      "value": "${!event.source.value}"
    },
    {
      "type": "SetValue",
      "componentId": "idForTheToggleButton",
      "property": "buttonText",
      "value": "Toggle button: ${!event.source.value}"
    }
  ],
  "spacing": "@spacingSmall",
  "alignSelf": "center"
}

Then, a separate TouchWrapper in the document triggers SendEvent and includes the button ID idForTheToggleButton in the components array, as shown in the following example.

{
  "type": "TouchWrapper",
  "id": "idForTheTouchWrapper",
  "spacing": "@spacingSmall",
  "alignSelf": "center",
  "onPress": [
    {
      "type": "SendEvent",
      "arguments": [
        "textWasPressed",
        "Send this data to the skill"
      ],
      "components": [
        "idForTheToggleButton",
        "idForTheTextComponent"
      ]
    }
  ],
  "item": {
    "type": "Text",
    "id": "idForTheTextComponent",
    "color": "@colorAccent",
    "text": "Click to send a UserEvent to the skill."
  }
}

The user can select the toggle button repeatedly to flip its state between true and false. When the user then selects the "Click to send…" text, your skill receives the following UserEvent. Note that components includes idForTheToggleButton with its current checked state:

{
  "type": "Alexa.Presentation.APL.UserEvent",
  "requestId": "amzn1.echo-api.request.1",
  "timestamp": "2020-01-20T22:46:04Z",
  "locale": "en-US",
  "arguments": [
    "textWasPressed",
    "Send this data to the skill"
  ],
  "components": {
    "idForTheTextComponent": "Click to send a UserEvent to the skill.",
    "idForTheToggleButton": true
  },
  "source": {
    "type": "TouchWrapper",
    "handler": "Press",
    "id": "idForTheTouchWrapper"
  },
  "token": "token-provided-with-RenderDocument"
}

For an additional example that illustrates how you could create a handler for UserEvent with the ASK SDK, see Handle a UserEvent request in Use Alexa Presentation Language with the ASK SDK v2.

Interaction mode for widgets

The interaction mode for a user event defines the capabilities that you can use in your response to that event. You set the mode with the interactionMode flag on the flags property of the SendEvent command.

The interactionMode flag accepts one of two values:

  • STANDARD – Your widget can launch a full skill experience. For example, you could include a button that launches your skill and continues the skill session. With the standard interaction mode, your skill can return any standard response from the request, just as you would for a LaunchRequest or IntentRequest.
  • INLINE – Your widget can perform actions based on the event, but can't open a full skill experience or return output speech. For example, a button that stores data for later and silently refreshes the data displayed in the widget uses the inline mode. An event with the inline interaction mode restricts the type of responses you can send.

Valid response types

For a standard APL document, your skill can respond to the UserEvent request with a standard response. You can include any custom skill directives except for Dialog.Delegate.

The valid responses for a UserEvent sent from a widget depend on the interaction mode for the event:

  • STANDARD
    • The response can be a standard response with speech and directives.
    • You can include any custom skill directives except for Dialog.Delegate.
  • INLINE (default)
    • The shouldEndSession flag must be true. The skill session ends with the response.
    • The response can't include any output speech.
    • The response can't include any skill directives except for the Alexa.Presentation.APL.ExecuteCommands directive.

For both modes, your handler for the UserEvent can use the Data Store REST API to update the data store for the widget. For details, see the Data Store REST API Reference.

Error cases

When an error occurs, your skill receives a RuntimeError request.

The following table summarizes the possible error cases.

Error description Exception reason System response

UpdateIndexListData is missing a required field

N/A

Alexa rejects the incoming directive.

The directive payload, or any list item exceeds the maximum permitted length

N/A

Alexa rejects the incoming directive.

UpdateIndexListData has an unrecognized token or listId

INVALID_PRESENTATION_TOKEN or INVALID_LIST_ID

Alexa discards the incoming directive.

UpdateIndexListData or SendIndexListData specifies a listVersion which is greater than expected

N/A

The directive is sent to Alexa where it is buffered until intermediate directives are received & processed.

The directive is buffered longer than a specified duration.

MISSING_LIST_VERSION

Alexa continues to buffer the directive.

Alexa is unable or unwilling to buffer further out-of-order directives,for example, due to insufficient memory

MISSING_LIST_VERSION

Alexa discards the buffered directive with the greatest listVersion.

UpdateIndexListData or SendIndexListData specifies a listVersion which is lower than expected

DUPLICATE_LIST_VERSION

Alexa discards the incoming directive.

Skill returns an UpdateIndexListData with an unrecognized operation type

INVALID_OPERATION

Alexa discards the incoming directive and places the list in 'failed' state where it accepts no further updates.

Skill returns an UpdateIndexListData directive for a DynamicTokenList

INVALID_DATASOURCE

Alexa discards the incoming directive and places list in ‘failed’ state where it accepts no further updates.

Skill returns an insert, set or delete operation with index outside of the range of permitted values.

LIST_INDEX_OUT_OF_RANGE

Alexa discards the incoming directive and places the list in 'failed' state where it accepts no further updates.

A list receives an UpdateIndexListData directive after a SendIndexListData directive which did not specify a listVersion.

MISSING_LIST_VERSION_IN_SEND_DATA

Alexa discards the incoming directive and places the list in 'failed' state where it accepts no further updates.

A list receives a SendIndexListData directive which does not specify a listVersion after a UpdateIndexListData directive.

MISSING_LIST_VERSION_IN_SEND_DATA

Alexa discards the incoming directive and places the list in 'failed' state where it accepts no further updates.

SendTokenListData or SendIndexListData specifies an unexpected correlationToken.

N/A

The device discards the response directive.

Device does not receive a SendTokenListData response for a correlationToken within a configured timeout.

LOAD_TIMEOUT

If no response after several retries, the device assumes that the end of the list has been reached. An exception is reported for each retry attempt.

The device does not receive a SendIndexListData response for a correlationToken within a configured timeout.

LOAD_TIMEOUT

If no response after several retries, then the device assumes that no further scrolling is possible beyond the requested position in the list (unless the device has already loaded items beyond this point, in which case the device is to show 'blank' list entries at the requested indexes).

listId or pageToken value(s) are inconsistent with those expected for the correlationToken.

INCONSISTENT_LIST_ID / INCONSISTENT_PAGE_TOKEN

The device ignores listId and pageToken values and uses the values expected for the correlationToken.

SendTokenListData directive contains no items, and does contain a nextPageToken.

MISSING_LIST_ITEMS

The device scrolls using the nextPageToken.

The SendIndexListData directive contains no items.

MISSING_LIST_ITEMS

Alexa retries the lazy load request several times, or until the response min/max index indicates that the end of the list has been reached.

SendTokenListData directive contains no items, and does not contain a nextPageToken.

N/A

The device assumes the end of the list has been reached (in the request scroll direction).

Directive for a previously-requested page returns different nextPageToken than that in the previous response.

INCONSISTENT_PAGE_TOKEN

The device discards the new nextPageToken.

The nextPageToken duplicates a token already used elsewhere in the list.

DUPLICATE_PAGE_TOKEN

The device discards the duplicated token value and assumes field was null, and therefore has reached the end of the list.

Directive for a previously-requested page returns a different number of items than those in the previous response.

INCONSISTENT_PAGE_ITEMS

The device expands or contracts the list as if the newly-returned number of items had been returned in the previous response.

Any field is outside the integer value range.

N/A

Alexa discards the response directive.

The response specifies items at indexes which are already populated in the device's cache.

OCCUPIED_LIST_INDEX

Discard any item data for indexes which are already populated in the device cache.

The response contains items with a different startIndex than those requested.

N/A

Accept the items at the reported startIndex (assuming that no items were previously loaded at these locations), and continue from the incoming index.

The maximumExclusiveIndex value is exceeded by returned item indexes.

LOAD_INDEX_OUT_OF_RANGE

Device displays items included in the maximumExclusiveIndex range, i.e. from startIndex to maximumExclusiveIndex - 1.

The response contains a different minimumInclusiveIndex or maximumExclusiveIndex than previously reported non-null value(s).

INCONSISTENT_RANGE

Device discards all previously loaded list items and repopulates the list afresh, starting with the startIndex, minimumInclusiveIndex & maximumExclusiveIndex parameters and item details as specified in the response.

The SendIndexListData response contains more items than the number requested.

N/A

Process as if the items had been requested and discard items at already-populated indexes.

The SendIndexListData response contains fewer items than the number requested.

N/A

Make a followup request for the remaining items (assuming that min/max indexes do not indicate that the end of the list has been reached).

Viewport object in the skill request

Every request sent to your skill includes information about the supported viewports for the user's device. You can use this information in your code to craft appropriate responses.

For a device with a screen, the viewport information is in the context.Viewport object.

Viewport information is also available in the data-binding context in the viewport property. The specific information available in the data-binding context differs from the information available in the skill request. For details, see Viewport Object in the Data-binding Context.

  • Use the context.Viewport object in the skill request when you need viewport information in your skill code.
  • Use the viewport property in the data-binding context when you need viewport information in your APL document, such as for creating a when condition to show a particular component only on certain viewports. See Viewport Object in the Data-binding Context

This example shows a skill request with the context.Viewport object, with some details removed for brevity:

{
  "version": "1.0",
  "session": {},
  "context": {
    "Viewports": [
      {
        "type": "APL",
        "id": "main",
        "shape": "RECTANGLE",
        "dpi": 213,
        "presentationType": "STANDARD",
        "canRotate": false,
        "configuration": {
          "current": {
            "mode": "HUB",
            "video": {
              "codecs": [
                "H_264_42",
                "H_264_41"
              ]
            },
            "size": {
              "type": "DISCRETE",
              "pixelWidth": 1280,
              "pixelHeight": 800
            }
          }
        }
      }
    ],
    "Viewport": {
      "experiences": [
        {
          "arcMinuteWidth": 346,
          "arcMinuteHeight": 216,
          "canRotate": false,
          "canResize": false
        }
      ],
      "mode": "HUB",
      "shape": "RECTANGLE",
      "pixelWidth": 1280,
      "pixelHeight": 800,
      "dpi": 213,
      "currentPixelWidth": 1280,
      "currentPixelHeight": 800,
      "touch": [
        "SINGLE"
      ],
      "video": {
        "codecs": [
          "H_264_42",
          "H_264_41"
        ]
      }
    },
    "Extensions": {
      "available": {
        "aplext:backstack:10": {}
      }
    },
    "System": {}
  },
  "request": {}
}

Viewport properties

The following properties are defined in the Viewport object.

Property Type/Values Description

experiences

Array of experience objects

Different modes in which the customer is expected to interact with the viewport.

mode

One of: HUB, TV, PC, MOBILE, AUTO

The mode for the device.

shape

ROUND or RECTANGLE

Shape of the viewport.

pixelHeight

Integer

Height of the viewport in pixels.

pixelWidth

Integer

Width of the viewport in pixels.

currentPixelWidth

Integer

Width of the viewport in pixels that is currently in use.

currentPixelHeight

Integer

Height of the viewport in pixels that is currently in use.

dpi

Integer

Pixel density of the viewport.

touch

Array of strings

Touch events that the viewport supports.

keyboard

Array of strings

Input mechanisms for interacting with the viewport.

video

Object

Specification of which technologies are available for playing video on a device

experiences

The experiences property contains a list of experience types supported by the device. The experience types depend on the modes supported by a viewport. You can use this information to optimize your skill's behavior for a specific experience. For example, a tablet device might have two different experiences: one for when it is docked and the other for when the customer is holding it. In these cases the skill's visual response should be optimized for both experiences, as the device owner can arbitrarily switch between the experiences.

experience properties

Property Type/Values Description

canRotate

Boolean

Whether the viewport can be rotated through 90, 180, and 270 degrees.

canResize

Boolean

Whether the viewport can be resized.

The experiences property also reports the deprecated arcMinuteWidth and arcMinuteHeight properties. Although these properties are available, they are deprecated. Use the mode property to determine the viewing distance and available modalities for the device instead.

mode

Represents the type of device.

pixelHeight and pixelWidth

The pixelHeight and pixelWidth properties represent the number of pixels present in the viewport at its maximum height and width. These values assume a static device orientation, and express the entire viewport size regardless of whether areas of the viewport are currently in use by other applications.

currentPixelWidth and currentPixelHeight

The currentPixelWidth and currentPixelHeight properties represent the number of horizontal and vertical pixels that are available for Alexa to render an experience. These values also assume a static device orientation.

shape

The shape of the screen is either ROUND or RECTANGLE.

dpi

The display-independent pixel (dp) measurement of a screen is an artificial value that represents the visual size of the screen assuming that the screen is held at a mobile-phone viewing distance and has a pixel density of approximately 160 pixels per inch. Two screens viewed at the same distance with the same physical size have approximately the same dp dimensions regardless of the actual pixel density of the screen.

The dots-per-inch (dpi) of a viewport is an artificial value that reflects the visual size of a point or pixel relative to the observer, and it does not match the actual pixels-per-inch size of the screen. The formula for dpi is:

dpi = 160 * (pixelSize / dpSize)

For simplicity, dpi values are simplified to fall into consistent buckets of 120, 160, 240, 320, and so forth.

touch

The touch property represents what kind of touch inputs the device supports. The touch array can contain the following values:

  • SINGLE - indicates that the device supports single-touch inputs

keyboard

The keyboard property represents physical button input mechanisms that can be used to interact with the viewport. The keyboard array can contain the following values:

  • DIRECTION - there are inputs for the up/down/left/right directions as well as a button to select whatever is at the current location

video

The video property details which technologies are available for playing video on a device. Use the video properties to determine what types of video resources to send in an APL response. For example, your skill's APL response could return video resources with different encodings depending on the video codec level that a device supports.

Note that some devices with screens do not support video playback. In this case, the video property is not present. If your skill includes video, be sure to check for this property and provide an appropriate experience for devices that do not support video. If you send a Video to a device that does not support video, the component remains on the screen, but displays no content so users will see a blank area on the screen.

video properties

Property Type/Values Description

codecs

Array of Strings

The video codecs that the output device supports. Supported values:

  • H_264_41: H.264 at a maximum resolution of 1080p @ 30fps (codec level 4.1) and supporting the main- and high-capability profiles (MP and HP).
  • H_264_42: H.264 at a maximum resolution of 1080p @ 60fps (codec level 4.2) and supporting the main- and high-capability profiles (MP and HP).

H_264_41 is a subset of H_264_42. All skill requests that specify H_264_42 will also specify H_264_41. All video-capable devices support the MPEG-4 Part-14 container (MP4), along with AAC and MP3 audio codecs.

Access the viewport information in your code

The Alexa Skills Kit SDKs includes functions that use data in the skill request context to calculate a viewport profile for the device. These functions are deprecated and aren't recommended. Instead, use the @viewportProfile resource in the viewport profiles package to create APL documents that adapt to different devices.

For details about the @viewportProfile resource and responsive documents, see the following:

The following functions are deprecated and not recommended:

For a list of deprecated features in the Alexa Skills Kit, see Deprecated Features.

APL visual context in the skill request

The Alexa Presentation Language (APL) visual context provides your skill with information about the content displayed on the screen when the user invokes an intent or triggers a user event. Your skill can use the context to determine the state of on-screen elements, such as which parts of a list are visible on the screen.

A request sent to your skill includes the visual context when the user's device has a screen and the screen is displaying an APL document your skill sent with the RenderDocument directive.

The visual context is available in the Alexa.Presentation.APL property within the top-level context property in the request.

{
  "version": "1.0",
  "session": {},
  "context": {
    "Viewports": [],
    "Alexa.DataStore.PackageManager": {
      "installedPackages": []
    },
    "Viewport": {},
    "Extensions": {},
    "System": {},
    "Alexa.Presentation.APL": {
      "token": "helloworldWithButtonToken",
      "version": "AriaRuntimeLibrary-2023.2.449.0",
      "componentsVisibleOnScreen": [
        {
          "uid": ":1000",
          "position": "960x480+0+0:0",
          "type": "text",
          "tags": {
            "viewport": {}
          },
          "children": [
            {
              "id": "fadeHelloTextButton",
              "uid": ":1002",
              "position": "273x76+344+360:0",
              "type": "text",
              "tags": {
                "focused": false,
                "clickable": true
              },
              "entities": []
            }
          ],
          "entities": []
        }
      ]
    }
  },
  "request": {}
}

For details about the objects provided in the visual context, see APL Visual Context in the Skill Request.

Service Interface Reference (JSON)

Request Format and Standard Request Types:

Interfaces:


Was this page helpful?

Last updated: Nov 28, 2023