Subscribe to the Events API
Imagine a mild-mannered onboarding app — it’s instructive, interactive and reactive, and in this case it is built on Slack. If you watch the GIF below you can find just that! An onboarding app that updates its training message after the user completes each step of onboarding. Here’s the hitch: this app isn’t built with the RTM API, and it isn’t polling Slack for updates — it’s built with something lovely and new, the Events API.
The Events API is a new way to build apps that respond to activity as it happens, in Slack. Previously, the only way to make apps that respond to activity outside of Slash Commands or Message Buttons was to use the RTM API. The RTM API opens a websocket for every team connected and gives developers a fire hose of data. Slack is built with the RTM API, so it’s not going anywhere, but the RTM API usually provides too much data and too many websockets for developers to manage in a pleasant, productive way.
The Events API, on the other hand, is a tidy way to build with simplicity and scalability in mind. If the RTM API is a fire hose, the Events API is a watering can — easy to wield and useful. Instead of an endless stream of data, the Events API allows you to subscribe to only the events required for your app, delivered to you via HTTP.
This means you can make a simple single-event-driven app with much less work — for example, an app that tracks reacji (Slack’s emoji reactions) only requires subscribing to reaction_added or reaction_removed. It also means you can build for scale — if your app is installed by 30,000 teams, you still only subscribe to the events you’ve built for, no more, no less.
Today the Events API handles dozens of events, and we’ll continue to add more. You can get started using these steps:
1. Enable Events API support for your Slack App
There’s a new tab in town when configuring your Slack apps labeled “Event Subscriptions.” There you’ll find a toggle allowing you to turn on Events API support for your app. Or turn it off. And on again. So you can pause your subscriptions if you want.
2. Configure your server to verify and process Events API requests
We won’t send a team’s events just anywhere. First, we’ll need to verify the veracity of your connection by sending your SSL-enabled URL a confirmation code, which you’ll need to send back to Slack. The verification process is somewhat like an unfunny knock knock joke that you may have to facilitate with some light programming.
After this little handshake is complete, your specified URL will become the happy recipient of all the events you end up subscribing to. What you do with the events as you receive them is up to you and your application’s special purpose.
3. Subscribe to the events you want your application or bot user to observe or respond to
With your request URL figured out, you’ll need to choose which events to receive. You’ll find a simple interface for selecting those subscriptions on the same configuration page used to set up your request URL.
Though we haven’t talked about the OAuth scopes that correspond to specific event subscriptions, know that after saving this page you’ll begin receiving your requested events from teams that are already set up with those scopes.
And if you’re the proprietor of a bot user, you’ll find that the `bot` scope you already requested affords your bot authorization to subscribe to a collection of useful event types you may already be familiar with from the RTM API.
4. Secure the right permissions for your app
If you’ve had a Slack app for awhile, you’re likely already requesting the OAuth scopes you need to work with the Events API.
But if you’re building a new application, or if there are events you want to subscribe to associated with OAuth scopes you aren’t yet requesting, then you’ll need to negotiate them with the Add to Slack flow before your subscriptions will activate.
If you’re subscribing on behalf of a bot, you’ll only need the `bot` scope.
In any case, your application will only receive event subscriptions on behalf of the users, channels, and conversations it has directly been granted access to.
5. Eventually, process and respond to requests
Once you have everything set up, you’ll begin receiving events at your configured URL matching your subscriptions, as incited by team activity.
Your URL will need to understand the format of these events, based on the same event types already flowing through the RTM API in JSON. When dispatched by the Events API, events are wrapped with additional metadata helping you contextualize and validate an event’s provenance.
Bot users would take this opportunity to respond to certain trigger phrases and conversational transactions. An emoji reaction tracker might take it upon itself to cross-post a recently reacted-to message to a channel dedicated to those iconic messages. What will your app do?
Ever optimistic, the Events API wants you to acknowledge receipt of each event with a friendly HTTP 200 OK response. The Events API will also retry failing requests up to three times using an exponential backoff technique that will help you reach the nirvana of eventual consistency.
That’s all there is to it. If you want to see how we built the opening onboarding app, we’ve open sourced it, enjoy! We’ll be back with a tutorial and some overviews of how to use the Events API with the hosting provider of your choice. Any questions or comments? Let us know @slackapi.
