How to Build a Slack Bot with Claude Code

Building a Slack bot with Claude Code is faster than doing it manually. The setup overhead still trips developers up: OAuth scopes, event subscriptions, and ngrok stop many builds early.

Claude Code handles the structural work: Bolt framework setup, slash command handlers, event listeners, and OAuth flow. The session time goes to building the feature, not the scaffolding.

Key Takeaways

• Slack Bolt is the required framework: Bolt handles authentication, event routing, and middleware. Claude Code generates clean Bolt code for Node.js or Python when specified in CLAUDE.md.
• The Slack app dashboard is a prerequisite: Create your Slack App at api.slack.com before writing a single line of code. Tokens, scopes, and event subscriptions are all managed there.
• Socket Mode removes the ngrok requirement: A persistent WebSocket connection replaces the public URL requirement. This is the recommended default for internal bots.
• OAuth scopes determine what the bot can do: Every action requires a declared scope. Missing scopes produce silent failures that look like code bugs.
• The ack() timing rule is critical: Slash command handlers must call ack() within 3 seconds or Slack shows a timeout error to the user.
• Event-driven is the correct mental model: Slack calls your bot when something happens. The bot does not poll Slack.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

What Do You Need Before Writing Any Code?

Every Slack bot starts with a Slack App created at api.slack.com. The dashboard is where you collect the credentials and configure the permissions that make Claude Code's generated code functional.

Go to api.slack.com/apps, click "Create New App," choose "From scratch," name the app, and select the workspace. Do this before opening a code editor.

• Signing secret is credential one: Copy SLACK_SIGNING_SECRET from the Basic Information page immediately. It validates that incoming requests are genuinely from Slack.
• Bot token is credential two: SLACK_BOT_TOKEN (starts with xoxb-) appears on OAuth & Permissions after installing the app to a workspace. Add scopes before installing.
• Start with these four scopes: Add chat:write, commands, app_mentions:read, and channels:history to cover the most common bot actions from day one.
• Event Subscriptions require a live URL: Enable events, paste your server's /slack/events endpoint, and subscribe to the specific bot events your handlers will process.
• Socket Mode adds credential three: Enable Socket Mode in settings and generate a SLACK_APP_TOKEN (starts with xapp-). This replaces the public HTTP endpoint entirely.

How Do You Set Up the Slack Bot Project?

The project structure and CLAUDE.md configuration determine whether Claude Code generates consistent, deployable Bolt code or requires constant correction. Get both right before writing any handlers.

Install Bolt with npm install @slack/bolt and TypeScript support with npm install -D typescript ts-node @types/node. Create .env with the three token values before prompting Claude Code.

• CLAUDE.md needs the bot purpose: One sentence describing what the bot does, the framework (@slack/bolt with Node.js), and the environment variable names gives Claude Code the context to generate consistent code.
• Define the file structure upfront: Use src/listeners/commands.ts for slash commands, src/listeners/events.ts for event listeners, and src/listeners/actions.ts for interactive component callbacks.
• Entry file is the first generation task: Prompt Claude Code to generate src/index.ts with the Bolt App instance, listener registrations, and app.start(process.env.PORT || 3000), before any handlers.
• List slash commands in CLAUDE.md: Include the command name, description, and expected behavior so Claude Code generates the handler and the ack/respond pattern correctly.
• Socket Mode setting belongs in CLAUDE.md: Specify socketMode: true and appToken: process.env.SLACK_APP_TOKEN so every generated Bolt initialization uses the correct configuration.

For general project setup principles that apply across any Claude Code build, full stack app setup with Claude Code covers the approach.

How Do You Handle Events and Slash Commands?

Event listeners and slash command handlers are the two primary interaction patterns in every Slack bot. Claude Code generates both correctly when the handler type, event name, and response pattern are specified clearly.

The first handler to generate is the app mention handler. It works as a connectivity test before building anything more complex.

• App mention handler comes first: app.event('app_mention', async ({ event, say }) => { await say('Hello!') }) confirms the event subscription and token are working before you write real logic.
• Slash commands must ack() within 3 seconds: Call await ack() as the first line of every slash command handler. Slack shows a timeout error if the acknowledgment is delayed, even if the response eventually arrives.
• Specify the regex for message pattern matching: Claude Code generates app.message('keyword', ...) handlers cleanly. For pattern matching, include the regex in the prompt explicitly.
• Block Kit enables interactive components: Prompt Claude Code to generate both the Block Kit JSON payload and the corresponding app.action handler together. Separating them produces mismatched action IDs.
• Error handling needs explicit rate limit handling: Ask Claude Code to handle slack_bolt/RateLimitedError specifically. Generic error handlers miss the retry-after logic Slack requires.

For bots that trigger multi-step automated processes outside Slack, automating workflows with Claude Code agents covers how to connect bot events to broader automation pipelines.

How Do You Handle OAuth for Multi-Workspace Installation?

Most internal bots use a single workspace with a static bot token and skip OAuth entirely. OAuth is only required when the bot will be installed by multiple external workspaces.

If the bot is for your own team, skip this section. OAuth is required only when distributing via the Slack App Directory or install links to other organizations.

• Single-workspace bots use static tokens: One SLACK_BOT_TOKEN in .env handles everything. No OAuth flow, no installation store, no redirect URLs to manage.
• Multi-workspace bots need an installation store: Bolt requires a store for saving and retrieving per-workspace tokens. Prompt Claude Code to generate a Supabase or Prisma-backed implementation.
• Bolt handles the OAuth flow when configured: Pass installerOptions and installationStore to the Bolt App constructor. Prompt Claude Code to generate this configuration with your chosen database.
• Configure the redirect URL in the dashboard: Bolt automatically handles the /slack/oauth_redirect route. Set the matching URL in Slack App settings before testing the flow.
• Token storage is the security decision: The installation store holds workspace tokens. Use your existing database with row-level security rather than a separate credentials store.

How Do You Test a Slack Bot with Claude Code?

Socket Mode is the recommended local testing setup. It connects via WebSocket without requiring a public URL or ngrok, which removes the most common local development friction point.

Create a dedicated test Slack workspace before any testing. Never test slash commands and event handlers in a production workspace where mistakes affect real teammates.

• Socket Mode local testing is the default: Enable Socket Mode in the Slack App dashboard, add SLACK_APP_TOKEN to .env, and run the bot locally. No public URL needed.
• ngrok works for HTTP mode testing: Run ngrok http 3000, copy the HTTPS URL, and paste it into Event Subscriptions in the Slack App dashboard. The URL changes on every ngrok restart.
• Manual test sequence is four steps: Install the bot in the test workspace, invite it to a channel with /invite @botname, trigger the slash command or mention, and confirm the response.
• Claude Code diagnoses from terminal error output: When a handler fails, copy the full error text from the terminal and give it to Claude Code. Bolt logs include the event payload, which is the most useful context for debugging.
• Unit tests mock Bolt's core functions: Ask Claude Code to write Jest tests mocking say, ack, and respond. Test handler business logic, not Slack API calls.

How Do You Deploy the Slack Bot?

Slack bots need a persistent process, not a serverless function. HTTP mode requires a public HTTPS URL. Socket Mode requires a long-lived WebSocket connection that most hosting platforms maintain automatically.

Railway and Fly.io are the two most practical deployment targets. Both keep the process alive and handle the environment variable management that Slack token security requires.

• Railway deployment is three steps: Connect the GitHub repository, add environment variables in the Railway dashboard, and deploy. Railway assigns a public URL for the event endpoint automatically.
• Fly.io works well for Socket Mode: Run fly launch, set secrets with fly secrets set, and deploy. Fly.io maintains the persistent connection with automatic restarts.
• Update the Event Subscriptions URL after deploying: Slack sends a verification challenge to the new URL immediately. Confirm the endpoint is live before updating the dashboard.
• All three tokens must be in the hosting platform's environment: SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET, and SLACK_APP_TOKEN for Socket Mode. Set them as secrets, not plain environment variables.
• Serverless has timing constraints: Serverless functions work for HTTP mode only, and the function must respond within Slack's 3-second ack window. Socket Mode is not compatible with serverless.

For strategies that speed up delivery timelines, delivering projects faster with Claude Code covers patterns that apply to bot and app builds alike.

How Does Slack Bot Development Compare to Other Bots?

Slack is the right platform for internal team tools and workspace automation. It is not the right platform for public audiences or browser-level functionality.

Understanding the trade-offs between platforms helps you pick the right channel before committing to a full build with Claude Code.

• Slack vs Telegram: Slack requires a workspace and review for public distribution. Telegram bots work for public audiences without approval. See building a Telegram bot with Claude Code for the Telegram process.
• Slack vs Discord: Similar event-driven architecture, different context. Slack is for professional workflows; Discord is for communities. Bolt and Discord.js have comparable event patterns.
• Slack vs Chrome extensions: Bots operate at the workspace level; extensions operate at the browser level. They solve different problems and are often complementary. See building a Chrome extension with Claude Code for extension-specific capabilities.
• Slack is best for internal tooling: HR helpdesks, IT bots, notification delivery to engineering teams, and workflow automation within a single business are where Slack bots add the most value.
• Internal bots bypass App Directory review: Single-workspace internal bots distribute via an install URL. No Slack review process, no approval wait.

Conclusion

Building a Slack bot with Claude Code goes fastest when the Slack App dashboard is configured before any code is written. Scopes, event subscriptions, and Socket Mode are dashboard decisions.

Once those are set, Claude Code generates correct Bolt handlers consistently. The most common failure points are missing OAuth scopes and missing ack calls.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

Need a Slack Bot Built for Your Team's Workflow?

Most internal tool requests start with a Slack bot: notification delivery, workflow triggers, helpdesk automation. They stall on Bolt setup and OAuth configuration before the first real feature gets built.

At LowCode Agency, we are a strategic product team, not a dev shop. We build Slack bots from dashboard configuration through production deployment, so you spend time on your feature, not Slack's infrastructure.

• Slack bot development with LowCode Agency: We scope, build, and deploy Bolt-based Slack bots with the event handlers, slash commands, and OAuth flows your use case requires.
• Dashboard and credentials setup: We configure the Slack App dashboard, collect the right tokens, and set OAuth scopes before any code generation begins.
• Socket Mode configuration: We set up persistent WebSocket connections for internal bots so local development and production deployment require no public URL management.
• Event handler and slash command build: We generate and test the full handler set using Claude Code with a structured CLAUDE.md so the code is consistent and maintainable.
• OAuth for multi-workspace distribution: We implement Bolt's OAuth flow with a database-backed installation store when bots need to scale beyond a single workspace.
• Production deployment and monitoring: We deploy to Railway or Fly.io with all token secrets properly configured and health check monitoring in place.
• Post-launch iteration: We stay available to add new slash commands, event handlers, and integrations as your team's workflow needs evolve.

We have built 350+ products for clients including Coca-Cola, American Express, and Medtronic.

If you want a Slack bot built correctly the first time, talk to us about your Slack bot.