Which API is right for your Slack app?
A cheat sheet for getting started with Slack’s APIs
Slack’s three most popular APIs help developers build all kinds of apps. Each has its merits, depending on your app’s use case — whether, for instance, your app needs to be notified of events, pull information from a Slack channel, or stream all events being sent within a team.
This article will walk you through Slack’s Web, Events, and RTM APIs, their common use cases, and where to get started using them. We’ve also included this simple flowchart to help you decide which API is best for your app.
But first, API Objects
Throughout all of the Slack APIs, you’ll encounter a set of seven core objects: channel, file, group, im, mpim, user, and usergroup.
These objects contain information about corresponding resources on a team. To read, write, or access the history of a resource, your Slack app should subscribe to an object’s OAuth scopes.
When someone grants your app these scopes on install (and soon, after install with the new Permissions API), you can use the APIs to access necessary resources. To learn more about these objects and the resources they correspond to, take a look at our object types documentation.
Web API
The Web API is your primary means to send rich, interactive messages in Slack. It’s made up of HTTP methods with similar calling conventions, and you can call these methods to send data to Slack and receive data back. The methods are designed to manipulate everything from Slack channels, to files, to emoji reactions that use a bearer token as a form of verification.
Use cases:
- Sending events, like messages from channel and DMs
- Creating and modifying Slack channels and user groups
- Uploading and editing files, message attachments, and reactions
- Backfilling state
Helpful links: Web API documentation, Web API supported methods, Node Slack SDK, Python Slack SDK, Ruby Slack Client, Sample Message Menus in Node (or Ruby!), Sample App Unfurls in Node
Events API
The Events API uses event subscriptions to send JSON payloads to your server. Your server is responsible for receiving the payload, then deciding how to respond — whether you call your own API, Slack’s API, or something else’s. You can subscribe to both team and bot user events from your Slack app’s setting page.
Use cases:
- Receiving events when users post messages, create or modify channels, or add or change files
- Receiving events when users add pins, stars, or reactions to channels
- Maintaining state in near real time
Helpful links: Events API documentation, Events API supported events, Events API Node module, Events API Python adapter, Sample Onboarding Bot in Node (or Python!)
RTM API
The RTM (real-time messaging) API uses WebSockets which allow you to receive events and send simple messages to Slack. The RTM API sends a stream of events to all connected clients after you send a request to the Web API (using rtm.connect or rtm.start. ) This can become very resource intensive, particularly if your app is installed on multiple or large Slack teams.
Use cases:
- Internal integrations that can only perform outgoing connections (in the case of a firewall, usually)
- Building a Slack client
- Maintaining state in near real time
Helpful links: RTM API documentation, Node Slack SDK, Python Slack SDK, Ruby Slack Client
Using Slack’s APIs
Most Slack apps use the Web API for sending messages and other information to Slack, but a common uncertainty we see from new developers is whether to use the RTM or Events API for receiving event payloads.
Generally, we recommend using the Events API, except for in a few specific cases (for instance, for an internal integration behind a firewall). When it comes down to it, the RTM API sends a lot of unnecessary information to your server over the connected WebSockets. This is particularly important if you have multiple connected clients, or just a large team using your app.
The Events API is newer and uses a subscription model. Your server only receives the information important to your app, and only subscribes to the permission scopes that your app requires to function. If you are having trouble deciding whether your app should use the RTM API, take a look at the flowchart above or read through the Slack API FAQ.
If you run into any trouble, reach out to our awesome community of developers in the Bot Developer Hangout, find us on Twitter, or get in touch with our developer support team at developers@slack.com. Happy developing! 🎉
