Slack is where most teams put their first AI agent, and it is where most of those agents quietly die. Not with an error — with a mute. Somebody clicks "Mute channel" in week two, the rest of the team follows, and six months later nobody can remember whether the thing still runs.
That failure is almost never about the model. It is about a handful of engineering and etiquette decisions made in the first afternoon. This guide is those decisions.
It assumes you already know why you want an agent in Slack rather than a chatbot — if not, that distinction is worth ten minutes — and that Slack is one integration in a larger picture, which is covered in the guide to agent integrations across your stack.
Decide what the agent is for before you touch the API
There are three genuinely useful patterns in Slack and a lot of unuseful ones. Pick one. Agents that try to do all three end up doing none of them well.
The responder. Someone @-mentions the agent with a question and it answers using access to your systems. High value, low risk, easy to evaluate — you can read the answers. This is where to start.
The watcher. The agent monitors something outside Slack — a Linear backlog, a Datadog alert stream, a Stripe webhook — and posts when something needs attention. Valuable but dangerous, because the failure mode is volume. A watcher that posts eleven times a day gets muted regardless of how correct it is.
The router. Something arrives in a channel and the agent decides where it goes: triages a bug report into Linear, escalates a customer message, tags an owner. Highest leverage of the three, and the one that most needs a human-approval step early on.
What does not work: the general-purpose assistant. "Ask me anything about the company" produces a demo that impresses in the all-hands and gets used four times. Narrow beats broad here for the same reason it does in picking your first automations — a narrow agent can be evaluated, and an agent that can be evaluated can be improved.
The scopes: ask for less than the docs suggest
Slack's OAuth scopes are granular, which is good, and the tutorials tend to grant far more than needed, which is not. Here is the minimum for a responder agent.
app_mentions:read— receive events when the agent is @-mentioned. This is the trigger.chat:write— post messages. Required for anything useful.channels:history— read messages in public channels the agent is a member of. Needed for thread context.users:read— resolve a user ID likeU024BE7LHinto a display name. Only if you actually show names.
That is it. Four scopes. Notably absent:
channels:read lets the app list every channel in the workspace including names and topics. Most apps request it out of habit and never call conversations.list. Skip it.
groups:history, im:history and mpim:history extend reading into private channels and DMs. Each is a meaningful escalation in what a compromised token exposes. Add them only when a specific feature requires it, and be able to name the feature.
files:read grants access to files shared in accessible conversations — often the most sensitive content in a workspace. If the agent must read attachments, add it and say so plainly in your internal documentation, because your security review will ask.
The pairing that deserves real scrutiny is broad history access combined with chat:write. Individually both are ordinary. Together they describe something that can read a large fraction of your internal conversation and send it somewhere. That is worth an explicit decision rather than an accumulated one.
One more thing worth doing on day one: invite the agent to channels rather than granting workspace-wide access. channels:history only applies to conversations the bot is a member of, so membership is your real access-control boundary. Use it. An agent in three channels has a comprehensible blast radius.
The 3-second rule, and why your bot is timing out
This is the single most common Slack agent bug, and it is structural rather than incidental.
Slack sends your app an event and expects an HTTP 200 within 3 seconds. Slash commands are the same. An LLM call — especially one that makes tool calls to look things up — takes somewhere between 2 and 30 seconds. So the naive implementation, where you receive the event, call the model, and return the answer as your HTTP response, fails intermittently at first and then constantly as your prompts grow.
The symptom is a dispatch failure notice or a operation_timeout, and it is maddening to debug because it works fine in a unit test.
The fix is to split acknowledgement from work:
- Receive the event. Validate the signature. Return 200 immediately — before any model call.
- Hand the work to a queue or background task.
- When the result is ready, post it with
chat.postMessage, or replace a placeholder withchat.update.
If you are using Slack's official Bolt SDK, this is what ack() is for, and the important detail is that ack() must be called before the slow work rather than after it. Plenty of code calls it at the end of the handler, which defeats the entire mechanism.
On placeholders: a "thinking…" message is acceptable if you replace it with the answer via chat.update. It is not acceptable as a permanent extra message. Two messages per interaction is how a channel becomes unreadable.
Socket Mode or Events API
Slack offers two delivery mechanisms and the right answer differs by environment.
Socket Mode opens an outbound WebSocket from your app to Slack, so events arrive over a connection you initiated. No public URL, no ngrok tunnel, no firewall exception, no request-signature verification. For local development this is straightforwardly better and removes the most tedious part of building a Slack app.
The Events API posts events to an HTTPS endpoint you host. You verify the X-Slack-Signature header using your signing secret and a timestamp check to prevent replay. More setup, but it scales the way ordinary web infrastructure scales — behind a load balancer, across regions, with no long-lived connection to manage per instance.
Our recommendation: Socket Mode while building, Events API in production. Bolt abstracts the difference well enough that switching is a configuration change rather than a rewrite, provided you have not littered request-specific assumptions through your handlers.
If you do use the Events API, verify signatures properly. Compare with a constant-time comparison, and reject timestamps older than five minutes. A Slack endpoint that skips verification is an unauthenticated command channel into your agent, which — given the agent has credentials to your other systems — is a genuinely serious hole rather than a theoretical one.
Rate limits, concretely
Slack's limits are documented but the practical consequences are not obvious.
Most Web API methods sit in Tier 3: roughly 50 requests per minute per workspace. That is generous for responding to mentions and immediately insufficient for reading history. conversations.history returns up to 200 messages per call, so a 10,000-message channel is 50 calls — your entire minute's budget for one channel's backfill.
chat.postMessage is special-cased at approximately one message per second per channel, with short bursts tolerated. A watcher agent that fires ten alerts at once will have several silently delayed.
Three rules that keep you out of trouble:
- Honour
Retry-After. A 429 response includes it. Immediate retries make the problem worse and can extend the penalty. - Cache user and channel lookups. Display names change rarely. Resolving the same user ID forty times in one thread is forty wasted calls against a shared budget.
- Never backfill history synchronously on startup. If the agent needs context, fetch the current thread with
conversations.replies— cheap and bounded — rather than the channel.
Remember the quota is per workspace, not per app. Your agent shares it with every other integration your team has installed. Budget for being one of several consumers, and track your own 429 rate as a metric rather than discovering it during an incident.
The etiquette that decides whether it survives
Everything above is engineering. This part is why bots get muted, and it gets far less attention than it deserves.
Always reply in-thread. Pass thread_ts. An agent that replies in-channel turns a 12-message channel into a 40-message channel, and the humans lose the thread of their own conversation. Use reply_broadcast only when a human explicitly asks for it.
Never post to say you are working. Use a reaction instead — reactions.add with an eyes emoji communicates "seen, working on it" at zero cost to the channel. Swap it for a checkmark when done. This one change measurably improves how people feel about a bot.
Be quiet by default. Respond to mentions. Do not respond to every message in a channel just because you can read it. An agent that interjects unprompted is the fastest possible route to a mute.
Give it an off switch that any member can reach. Not "ask an admin to uninstall the app." A /agent pause command, or a channel-level opt-out. If the only available control is mute, mute is what you will get — and a muted bot is worse than no bot, because it looks like it is working.
Show your sources. When the agent answers from a Notion page or a Zendesk ticket, link it. This costs one line and converts "I don't trust this" into "I can check this," which is the difference between a tool people use and a tool people tolerate.
Say when you do not know. An agent that answers everything confidently gets caught being wrong once and loses credibility permanently. One that says "I couldn't find anything about that in the runbooks — try #platform-help" is trusted the next time it does answer.
Things that will bite you
A short list of the specific surprises, in rough order of how likely you are to hit them.
Retries create duplicates. If your endpoint does not return 200 fast enough, Slack retries — and delivers the same event again, with the same event_id. Without deduplication your agent answers the same question three times. De-dupe on event_id with a short TTL cache.
The bot hears itself. Message events include messages your own bot posted. If you react to messages generally rather than only to mentions, you will build an infinite loop and discover it in production. Filter on bot_id and your own user ID.
Message formatting is mrkdwn, not Markdown. Single asterisks for bold, underscores for italics, no heading syntax at all. Models emit standard Markdown by default, so ## Heading renders literally as ## Heading. Either post-process the model output or use Block Kit, which is more work and looks considerably better.
Long messages are truncated. The practical limit is about 3,000 characters per text block and 4,000 per message. Model output routinely exceeds that. Split deliberately or link to somewhere fuller — do not let Slack decide where your answer ends.
Token rotation breaks things silently. When a bot token is revoked, calls fail with invalid_auth. If your error handling logs and continues, the agent simply stops working with no visible cause. Alert on invalid_auth and token_revoked separately from generic errors — this is the "month three" failure described in the integrations guide and it is the most common reason an agent that used to work no longer does.
How to tell whether it is working
Decide the metric before you launch, because after launch everyone will have opinions and no data.
For a responder: what fraction of mentions get an answer the asker did not have to follow up on? Count the follow-ups — they are your error rate, and they are visible in the thread without any instrumentation.
For a watcher: what fraction of posts got a human reaction or reply? A watcher whose messages nobody responds to is producing noise, no matter how accurate it is.
For a router: what fraction of routing decisions were overridden? Under 10% and you can probably remove the approval step. Over 30% and the agent is guessing.
Track mutes too, if your Slack plan's analytics expose channel membership changes. It is the clearest signal you have, and it is the one nobody thinks to look at.
Where to go from here
Slack is the easiest integration to get working and the easiest to get wrong socially. Once it is stable, the next question is usually what to connect behind it — the CRM, the ticket queue, the knowledge base — and in what order. That sequencing is the subject of the integrations guide.
If you are still weighing whether an agent is the right shape of solution at all, rather than a workflow tool with a webhook, the comparison with Zapier, Make and n8n is worth reading first. A surprising number of "we need an AI agent in Slack" requirements are better served by a workflow with three steps, and it is cheaper to find that out before you write the OAuth flow.
Frequently asked questions
Which Slack scopes does an AI agent actually need?
For a read-and-reply agent: app_mentions:read, chat:write, and channels:history limited to the channels you invite it to. Add users:read only if you need display names, and files:read only if the agent must open attachments. Skip channels:read unless you genuinely enumerate channels — it is broader than most people assume.
Should I use Socket Mode or the Events API?
Socket Mode in development, the Events API with a public HTTPS endpoint in production. Socket Mode needs no inbound firewall rule or tunnel, which removes the single most annoying part of local development. It does hold an open WebSocket per app instance, so for multi-region production deployments the request-based Events API scales more predictably.
Why does my Slack bot show 'operation_timeout' or a dispatch failure?
Slack requires an HTTP 200 within 3 seconds of delivering an event or slash command. An LLM call takes longer than that. You must acknowledge immediately and do the work afterwards, then post the result with chat.postMessage or by updating the original message. Almost every 'my bot randomly fails' report is this.
How do I stop a Slack AI agent from being annoying?
Reply in-thread using thread_ts, never with reply_broadcast. Respond only when mentioned or in channels explicitly opted in. Never post a message whose only content is that the agent is working. And give it an off switch a non-admin can use — if muting is the only available control, people will mute it.
What are Slack's rate limits for a bot?
Most Web API methods are Tier 3, roughly 50 requests per minute per workspace. chat.postMessage is special-cased at about one message per second per channel with short bursts tolerated. Reading long history is what exhausts quota, so page conversations.history slowly and cache. Always honour the Retry-After header on a 429 instead of retrying immediately.