Alexa.Presentation.APL 1.1

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.

• Capability assertion
• Context
  • RenderedDocumentState
• Events
  • LoadIndexListData
  • UserEvent
  • RuntimeError
• Directives
  • RenderDocument
  • ExecuteCommands
  • SendIndexListData
  • UpdateIndexListData

Capability assertion

A device may implement Alexa.Presentation.APL 1.1 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.1",
  "configurations": {
    "runtime": {
      "maxVersion": {{STRING}}
    }
  }
}

runtime

Because APL is backward-compatible, a content author could send any APL document declaring a version of APL up to the maxVersion. For example, a content author shouldn't send an APL document requiring 1.3 features to a device that only supports up to 1.2 version of the runtime, but the author could send a document declaring 1.0, 1.1, or 1.2. For more details, see APL document version property.

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

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

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.

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.

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.

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}}
         },
    }
}

Payload parameters

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

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:

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:

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:

InsertItem:

InsertMultipleItems:

SetItem:

DeleteItem:

DeleteMultipleItems: