Register and Dispatch an Event Handler

Slack provides the Events API to simplify how your app responds to activities. Make sure that you enable event subscriptions on your Slack app, and then select the event types that you want to subscribe to.

When creating your Slack app at api.slack.com/apps/, you can add or remove event subscriptions in one of several ways.

  • In the app manifest on the App Manifest page
  • On the Event Subscriptions page

Events aren’t the same as user-triggered actions. For user-triggered actions, see Interactive Components.

To handle an event, register the event handler by defining it in your app metadata and create an Apex class that extends the Slack.EventDispatcher. You must also specify an integration user to run your Slack events in Salesforce.

Register the event handlers in your .slackapp file. For example, define apex__action__AppHomeOpened if you're handling the app_home_opened event in an Apex class named AppHomeOpened.

For synthetic events, register them in the .slackapp file. However, you don't need to define synthetic events in the app manifest at api.slack.com/apps/.

Message events are represented by the Slack.MessageEvent class. Use Slack.MessageEvent to handle Slack events of message type. The message event type includes:

  • message.app_home
  • message.channels
  • message.groups
  • message.im
  • message.mpim

In your .slackapp file, use the events.message property to define your handler for any message.* events.

Use the channel_type property to determine the message.* event you're handling. For example, the message.im type returns channel_type with the im value.

Additionally, message events can have a subtype. For example, the channel_join subtype is represented by the Slack.MessageChannelJoinEvent class. For more information, see how the events map to Slack Apex classes.

For a full list of message subtypes, see Message subtypes in the Slack API documentation.

Some events contain subclasses that are included in their payloads. For example, the channel_rename event is represented by the Slack.ChannelRenameEvent class. It returns the channel property represented by the Slack.ChannelRenameEvent.Channel class.

To implement an event handler, extend the Slack.EventDispatcher class.

Event handlers receive these properties from Slack.RequestContext.

  • appId—The app's unique ID.
  • channelId-The channel ID.
  • enterpriseId—The organization ID for Enterprise Grid. null values are accepted.
  • teamId—The Slack workspace ID.
  • userId-The Slack user ID.

For example, the app uses the user ID from the event payload and displays a view. You can publish your view using the Slack.ViewsPublishRequest and Slack.ViewsPublishResponse classes. For an example, see Onboarding with App Home.

When the event is invoked, you receive the event parameters using the Slack.Event class. For example, you can handle the group_rename event using Slack.GroupRenameEvent and respond with a message using Slack.ChatPostMessageResponse in the run() method of your event handler.

Similarly, you can get the parameters using the corresponding Apex class for the Slack event. For example, use the Slack.AppHomeOpenedEvent class for the app_home_opened event.

The Apex SDK sample app provides examples on event handling. See Sample Apex SDK for Slack App.

Apex SDK for Slack is subject to Slack's rate limits. Slack’s Event API invokes the app_rate_limited event when a single app receives more than 30,000 events in a single hour from a single workspace. It's automatically sent when your app's event subscriptions are rate limited or disabled.

Apex SDK for Slack apps automatically subscribes to app_rate_limited. But a default event handler is unavailable. To determine if your Slack client has reached a rate limit error, look for these fields in the response.

  • ratelimited: Most Apex classes that call Slack Client API methods include this field, which means that your request is rate limited and you must wait a certain period before retrying the request.
  • rate_limited: For Apex classes calling Slack Client API methods that involve posting to a channel, this field is included in the response if the app posted too many messages. Apps aren’t allowed to post more than one message per second per channel, although short bursts that exceed the limit are allowed.