Interactive Components

Your app binds service logic to components that are rendered in Slack. When users interact with these components, such as when they click a button, select a value in a picker, or submit a view, your app can run custom logic in response.

In your component's ViewDefinition configuration file, associate an action with an event. An action is like an event handler, the code runs when a component event fires.

To create an action associated with block_actions, view_submission, and view_closed requests, create a class that extends Slack.ActionDispatcher.

When you implement modals, there are several different user interactions that can happen. For example, when a user interacts with an element in your app's modal views, the app receives a block_actions payload. For more information, see Handling interactions in modals.

block_actions Payload

The block_actions payload is returned when a user interacts with an element in your app's modal views. See Handling block_actions payloads.

Actions handlers receive these properties from RequestContext when the payload is block_actions:

  • appId—The application's unique ID.
  • channelId—The channel where the source message was located.
  • enterpriseId—The organization ID for Enterprise Grid. null values are accepted.
  • userId—The Slack user's user_id associated with this request.
  • teamId—The Slack workspace ID.
  • triggerId—A temporary ID generated for the interaction in your app. This value can be used to open modals.
  • View—The view context for the action or null if the action didn’t originate from a view.
    • id—The ID of the view.
    • hash—A unique value that's optionally accepted in views.update and views.publish API calls. When provided to those APIs, the hash is validated such that only the most recent view can be updated. This validation ensures the correct view is being updated when updates are happening asynchronously.
  • Message—The message that the user initiated the shortcut from.
    • text—The text of the message.
    • ts—The timestamp of the message.
    • userId—The ID of the user who initiated the action.
  • ActionPayload—Contains the name and values associated with the block element that triggered the action.
    • name—The name of the block element.
    • type—The type of block element.
    • value—The value of the block element.
    • formData—The input fields defined in the view.

view_closed Payload

Your app can optionally receive view_closed payloads whenever a user clicks the Cancel or x buttons. These buttons are standard in all app modals. See Handling view_closed payloads.

Actions handlers receive these properties from RequestContext when the payload is view_closed:

  • appId—The application's unique ID.
  • enterpriseId—The organization ID for Enterprise Grid. null values are accepted.
  • userId—The Slack user's user_id associated with this request.
  • teamId—The Slack workspace ID.
  • triggerId—A temporary ID generated for the interaction in your app. This value can be used to open modals.
  • View—The view context for the action or null if the action didn’t originate from a view.
    • id—The ID of the view.
    • hash—A unique value that's optionally accepted in views.update and views.publish API calls. When provided to those APIs, the hash is validated such that only the most recent view can be updated. This validation ensures the correct view is being updated when updates are happening asynchronously.

view_submission Payload

When a modal view is submitted, your app receives a view_submission payload. See Handling view_submission payloads.

Actions handlers receive these properties from RequestContext when the payload is view_submission:

  • appId—The application's unique ID.
  • enterpriseId—The organization ID for Enterprise Grid. null values are accepted.
  • userId—The Slack user's user_id associated with this request.
  • teamId—The Slack workspace ID.
  • triggerId—A temporary ID generated for the interaction in your app. This value can be used to open modals.
  • View—The view context for the action or null if the action didn’t originate from a view.
    • id—The ID of the view.
    • hash—A unique value that's optionally accepted in views.update and views.publish API calls. When provided to those APIs, the hash is validated such that only the most recent view can be updated. This validation ensures the correct view is being updated when updates are happening asynchronously.
  • formData—The input fields defined in the view.

To associate an action with a component event, reference the action from a ViewDefinition configuration file using this syntax.

Component events are not the same as app-level events.

The action name for the component event and the properties definition, such as the objectApiName value, are encoded and sent back as the action_id through Slack. The action name and properties you add for the action_id are subject to Slack's 255 character limit. See Action Signing.

Handle a Button Click

To trigger an action on a button click, specify the action in the view definition.

In this example, an action runs when the onclick event fires. The definition runs the createRecord Apex class.

The createRecord Apex class extends Slack.ActionDispatcher and responds to the button click event in the previous example.

To work with other dispatchers to handle an event, shortcut, or slash command, see Create an Apex Handler.

Apex SDK for Slack translates your view definitions into Slack user interfaces using Block Kit. As part of the translation, your actions are returned to Slack as part of Slack's action_id field.

Action signing prevents malicious alterations to the actions when the users are viewing and interacting with them.

To support action signing, 20 characters of the component's action_id value is reserved for a unique string. Slack has a 255 character limit for action_id fields.

For interactive elements within messages, we recommend that you don't exceed 225 characters for the action name and its properties to allow for delimiters and URL encoding. Modals and homepage views can accommodate for more action properties; however, there’s a limit of approximately 2500 characters.

To ensure that you are within the 255 character limit, shorten the action identifier or the name of the action properties. Otherwise, the message doesn't render correctly in Slack.

Action signing is a security enhancement introduced in March 2022. Starting April 9, 2022, actions in messages that were posted before March 9, 2022 display an error icon and no longer work.