--- schema_version: "1" id: 4bf9eb47d4084ce0da982638abeba33a3b01247e0d7e9a6f6f0141ba2db8ebd9 title: Register and Dispatch an Event Handler collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/salesforce-slack-sdk/apex-slack-sdk/guides/build/events_handling.md canonical_url: https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/events_handling.html source_site: developer.salesforce.com content_type: documentation content_hash: 0d6898b2bdbd082f9d046d8e007caef7e846fe46e2627dd896ba4fdd61d867e0 products: - Apex SDK for Slack (Beta) --- # Register and Dispatch an Event Handler Slack provides the [Events API](https://api.slack.com/events) 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/](https://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 **tip:** Events aren’t the same as user-triggered actions. For user-triggered actions, see [Interactive Components](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/actions_handlers_write.md). 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](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/events_integration_users.md) to run your Slack events in Salesforce. ## Register an Event Handler 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`. ```yaml description: App Home Example App # Other command and shortcut definitions here # Define the action binding for the app_home_opened event events: app_home_opened: action: definition: apex__action__AppHomeOpened title: Example event handler for app_home_opened description: Event fires when a user opens the home tab. ``` For [synthetic events](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/events_mapping.md#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/](https://api.slack.com/apps/). ## Register a Message Event Handler Message events are represented by the [Slack.MessageEvent](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/apex_ref/apex_ref_events.md#messageevent-class) 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. ```yaml description: Handle Message.* Events name: MessageDemoApp events: message: action: definition: apex__action__messageEvent title: Event handler for various message.* events description: Use the events.message property to define your message.* event handler ``` 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. ```json "event": { "type": "message", "channel": "C0000000005", "user": "U0000000001", "text": "This is a message from a DM", "ts": "1648762903933", "channel_type": "im" } ``` Additionally, `message` events can have a subtype. For example, the `channel_join` subtype is represented by the [Slack.MessageChannelJoinEvent](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/apex_ref/apex_ref_events.md#messagechanneljoinevent-class) class. For more information, see [how the events map to Slack Apex classes](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/events_mapping.md). ```yaml { "type": "message", "subtype": "channel_join", "text": "Someone has joined the channel", "ts": "1403051575.000407", "user": "U023ABCDE", } ``` For a full list of message subtypes, see [Message subtypes](https://api.slack.com/events/message#subtypes) in the Slack API documentation. **tip:** Some events contain subclasses that are included in their payloads. For example, the [`channel_rename` event](https://api.slack.com/events/channel_rename) is represented by the [Slack.ChannelRenameEvent](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/apex_ref/apex_ref_events.md#channelrenameevent-class) class. It returns the `channel` property represented by the Slack.ChannelRenameEvent.Channel class. ## Dispatch an Event Handler To implement an event handler, extend the [`Slack.EventDispatcher`](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/apex_ref/apex_ref_dispatchers.md#eventdispatcher-class) class. ```java public class EventDispatcherExample extends Slack.EventDispatcher { public override Slack.ActionHandler invoke(Slack.EventParameters parameters, Slack.RequestContext context) { return Slack.ActionHandler.ack(new Handler(parameters, context)); } public class Handler implements Slack.RunnableHandler { Slack.EventParameters parameters; Slack.RequestContext context; public Handler(Slack.EventParameters parameters, Slack.RequestContext context) { this.parameters = parameters; this.context = context; } public void run() { // Do something with the runnable handler // such as updating the app home view // or posting a message } } } ``` Event handlers receive these properties from [`Slack.RequestContext`](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/apex_ref/apex_ref_requestcontext.md). - `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`](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/apex_ref/apex_ref_views.md#viewspublishrequest-class) and [`Slack.ViewsPublishResponse`](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/apex_ref/apex_ref_views.md#viewspublishresponse-class) classes. For an example, see [Onboarding with App Home](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/views_onboarding.md). 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`](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/apex_ref/apex_ref_chat.md#chatpostmessageresponse-class) in the `run()` method of your event handler. ```java Slack.App app = Slack.App.ApexSlackApp.get(); Slack.BotClient botClient = app.getBotClientForTeam(context.getTeamId()); Slack.Event event = parameters.getEvent(); String channelId = ''; String channelName = ''; if (event instanceof Slack.GroupRenameEvent) { Slack.GroupRenameEvent groupRenameEvent = (Slack.GroupRenameEvent) event; channelId = groupRenameEvent.getChannel().getId(); channelName = groupRenameEvent.getChannel().getName(); } else if (event instanceof Slack.ChannelRenameEvent) { Slack.ChannelRenameEvent channelRenameEvent = (Slack.ChannelRenameEvent) event; channelId = channelRenameEvent.getChannel().getId(); channelName = channelRenameEvent.getChannel().getName(); } Slack.ChatPostMessageResponse response = botClient.chatPostMessage( Slack.ChatPostMessageRequest.builder().channel(channelId).text('The channel was renamed to ' + channelName).build() ); ``` 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. ```java Slack.AppHomeOpenedEvent appHomeOpened = (Slack.AppHomeOpenedEvent) parameters.getEvent(); String userId = appHomeOpened.getUser(); ``` **tip:** The Apex SDK sample app provides examples on event handling. See [Sample Apex SDK for Slack App](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/setup-install-app.md). ## Rate Limits Apex SDK for Slack is subject to [Slack's rate limits](https://api.slack.com/docs/rate-limits). Slack’s Event API invokes the [app_rate_limited event](https://api.slack.com/events/app_rate_limited) 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. ## See Also - [Using the Slack Events API](https://api.slack.com/apis/connections/events-api) - [Welcome users to your App Home using events](https://api.slack.com/surfaces/tabs/events) - [Building a Home for your app](https://api.slack.com/tutorials/app-home-with-modal)