SendEvent Command

Generate and send an Alexa.Presentation.APL.UserEvent request to your skill. The UserEvent request includes information about the Alexa Presentation Language (APL) components and events that triggered the command.

Properties

The SendEvent command has the properties shown in the following table, in addition to the common command properties. Set the type property to SendEvent.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property Type Default Description

arguments

Array of objects

[ ]

An array of argument data to send to the skill in the UserEvent request.

components

Array of selector strings

[ ]

An array of components. The resulting UserEvent request includes the value associated with each identified component. Use the selector syntax to identify the components.

flags

Map

None

Optional map of flags that might be used by the runtime. Available flags:

The SendEvent command is ignored in fast mode.

arguments

An array of data to send to the skill in the UserEvent request. Data binding applies to each element in the array when SendEvent runs. This allows an argument to contain data about the event itself, such as ${event.source.value}. Use this to send arbitrary data to your skill.

Access this data in your UserEvent handler in the arguments property of the request.

components

The components property is an array of selector strings. The UserEvent request includes the value of each component. For example, you can use the components property to construct a form that sends the contents of each component to your skill.

The value for a given component depends on the type of component:

  • A component with a basic press interaction, such as a TouchWrapper, reports the checked state of the component.
  • A rich component that supports interaction, such as a Pager, Sequence, or ScrollView, reports component-specific values. For example, a Pager reports the index of the displayed page. Refer to component documentation for what they report.
  • Other components report null, unless stated otherwise the component documentation.

Access the component values in the components property of the request.

flags

Additional properties that might be used by the runtime or message routing system to customize the UserEvent behavior. The APL runtime might set default keys directly. Note that the UserEvent generated by the SendEvent command doesn't include the value of the flags property.

interactionMode flag

For a widget, set the flags property to the interaction mode for the request. The interaction mode for a user event defines the capabilities you can use in your response to that event. A widget supports the following values for flags.

Property Type Default Description

interactionMode

One of: INLINE, STANDARD

INLINE

Controls the interaction mode of the event, which dictates how your skill can respond.

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.

The following example shows the SendEvent command for a button in a widget. In this example, the interactionMode flag is INLINE.

{
  "type": "AlexaFooterActionButton",
  "id": "saveItemButton",
  "buttonText": "Save Item",
  "primaryAction": [
    {
      "type": "SendEvent",
      "arguments": [
        {
          "itemId": "ItemIDForSmokedWildSalmon"
        }
      ],
      "flags": {
        "interactionMode": "INLINE"
      }
    }
  ]
}

For more details the UserEvent request, see UserEvent.

UserEvent request sent to your skill

The SendEvent command sends the skill an Alexa.Presentation.APL.UserEvent request.

For example, the SendEvent defined in the TouchWrapper shown in SendEvent example generates the following UserEvent request.

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

This UserEvent includes the following information defined in the SendEvent command:

  • The arguments property is an array that contains the data passed to the arguments array of the SendEvent command. In this example, the array contains static strings, but you could use data-binding to include dynamic information here.
  • The source property contains an object that provides details about the component that triggered the event.
  • The components property contains the value of the component with the ID idForTheTextComponent. This component is a Text component. Therefore, the UserEvent includes the value of the text property. This value is included because the SendEvent included this same ID in the components array.

For more details about the UserEvent request, see UserEvent request.

For an example of a UserEvent handler, see Handle a UserEvent request.

SendEvent example

The following example illustrates a SendEvent command on the onPress handler of a TouchWrapper.

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

Last updated: frontmatter-missing