What we do
Tools
Industries
Department
How we workLet's talk →
Home/Slack/Slack API
Slack

The Slack API for Developers: The Pieces, a First Bot, and the Limits

"The Slack API" is really a few APIs that work together. The Web API is how your app does things in Slack. The Events API is how Slack tells your app something happened. Block Kit and interactivity give you buttons, menus and forms. Here's which piece does what, the shortest path to a working bot, and the limits worth designing for from day one.

Which part you need

Post, read or change things (messages, channels, users): the Web API, a set of HTTP methods such as chat.postMessage, called with a token.

React when something happens (a mention, a new message, someone joining): the Events API, which sends a request to your URL, or over a websocket if you use Socket Mode.

Let people click or type (buttons, menus, modals, /slash commands): Block Kit plus interactivity, which posts each action back to your app.

Want less boilerplate? Slack's Bolt frameworks for JavaScript, Python and Java handle token checks, request signing and acknowledgements for you.

From nothing to a bot that posts and listens

This is the private, single-workspace path. It needs no app directory review.

  1. 1

    Create the app

    api.slack.com/apps Create New App

    Start from scratch or from a manifest, and pick the workspace you'll develop in. A manifest is a YAML or JSON file describing the app's scopes and features, which makes the setup repeatable.

  2. 2

    Add bot scopes

    OAuth & Permissions Bot Token Scopes

    Request only what the app needs, for example chat:write to post and channels:history to read public channel messages. Every scope you add later means reinstalling the app.

  3. 3

    Install it and copy the bot token

    Install the app to your workspace. Slack gives you a bot token starting with xoxb-. Keep it server-side, like a password.

  4. 4

    Post a first message

    Call chat.postMessage with the token, a channel ID and some text. The bot has to be invited into a channel before it can post there, which is the most common first error.

  5. 5

    Subscribe to events

    Event Subscriptions Subscribe to bot events

    Add the events you care about, such as app_mention. Either give Slack a public Request URL (it sends a one-time challenge to confirm you own it) or switch on Socket Mode and connect with an app-level token starting with xapp-.

    Watch for: the 3-second rule. Slack expects your app to acknowledge every event, slash command and button click within 3 seconds, or it treats the request as failed and may retry. Acknowledge first, then do the slow work.

Pick the lightest tool that does the job

Not every Slack automation needs a full app. These are the usual choices, lightest first.

You need to Use It runs out when
Drop a message into one channel from another system An incoming webhook. See our Slack webhooks page You need to post to many channels, read anything, or respond to people.
Run a simple form or approval inside Slack with no code Workflow Builder. More on Slack workflows The logic needs your own data, branching rules or a system Slack doesn't have a connector for.
Answer questions or take actions against your own systems A bot on the Web API and Events API, with slash commands or buttons Rarely. This is the full toolset, and the limits below are what you design around.
Install into other companies' workspaces A distributed app with the full OAuth install flow, ideally listed in the Slack Marketplace You skip the Marketplace. Distributed apps outside it get much tighter limits on reading message history.

What breaks after the demo works

None of these show up with one tester in a quiet channel. All of them show up in production.

Rate limits on busy days

How you'll know: Calls start returning HTTP 429. Each Web API method sits in a tier, from about 1 call a minute (Tier 1) up to 100 or more (Tier 4), and posting is limited to roughly one message per second per channel.

Fix: Read the Retry-After header and wait that long, queue outgoing messages instead of firing them in a loop, and cache lookups such as user and channel lists.

Message history throttled for distributed apps

How you'll know: A commercially distributed app that isn't in the Slack Marketplace gets 1 conversations.history request a minute, returning at most 15 messages.

Fix: Apps built for your own workspace keep the higher limits. If you're selling the app to other companies and it reads history, plan for Marketplace approval or store events as they arrive instead of reading back.

Slow handlers trigger retries

How you'll know: The same event gets processed twice, or users see "operation timed out" on a slash command.

Fix: Acknowledge within 3 seconds and hand the work to a background job. Make handlers safe to run twice, because Slack retries events it thinks failed.

Messaging the right person, not just a channel

How you'll know: The bot needs to DM whoever owns a ticket, but you only have their email address.

Fix: Look up the user ID with users.lookupByEmail (needs the users:read.email scope), open a DM with conversations.open, then post. Keep that mapping fresh as people join and leave.

Scopes and tokens drift

How you'll know: A new feature needs a new scope, and the app quietly fails for every workspace that hasn't reinstalled.

Fix: Check granted scopes on startup, alert when a token is revoked, and prompt for a reinstall instead of failing silently.

Questions people ask

Is the Slack API free to use?

Yes. Slack doesn't charge for API calls, and a custom app for your own workspace works on any plan. The limits that matter are rate limits, plus a cap on how many apps a free workspace can install. Apps distributed to other companies outside the Slack Marketplace also get stricter limits on some methods.

Do I need to publish my Slack app to the app directory?

No. An app built for your own workspace installs straight from its settings page without any review. The Slack Marketplace only matters if you want other companies to find and install your app, and for distributed apps it also affects the rate limits you get.

What programming language do I need to build a Slack app?

Any language that can make HTTPS requests, because the Web API is plain HTTP and JSON. Slack's Bolt frameworks for JavaScript, Python and Java save a lot of boilerplate, but plenty of apps call the API directly from Go, Ruby, PHP or C#.

What's the difference between a Slack bot token and a user token?

A bot token (xoxb-) acts as the app's own bot user and is what most automation should use. A user token (xoxp-) acts as the person who authorized it, so it can do things only that person can, and its actions look like theirs. A third kind, the app-level token (xapp-), is used for Socket Mode connections.

Can a Slack bot message someone who never messaged it first?

Yes, with the right scopes. It needs the person's Slack user ID, not their name. If you have their email, users.lookupByEmail returns the ID. Then open a direct message with conversations.open and post to it.

Who builds custom Slack bots for a business?

Your own developers if you have them, or an outside team. n-frames builds custom Slack bots and slash commands for businesses: bots that look up orders, jobs or tickets in your own systems, DM whoever owns an issue, and post approvals with buttons that write back to the source system. We maintain them after launch too, so rate limits, token changes and reinstalls aren't your problem.

What is Socket Mode in Slack?

A way for your app to receive events and interactions over a websocket instead of a public HTTP endpoint. It suits internal tools running behind a firewall. Slack's docs steer apps meant for public distribution toward HTTP endpoints instead.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.