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.