Slack Integration Guide

Deploy your AI agent on Slack with complete configuration for OAuth scopes, bot events, and App Home. Once connected, your agent will reply in channels, private groups, threads, and direct messages (DMs).

High-level flow showing how the AI agent connects to Slack.

---

1. Create Your Slack App

To begin, create a workspace-linked Slack app.

Start a new workspace-linked Slack app from the Slack Developer Dashboard.

Steps:

1. Open the Slack API Dashboard: https://api.slack.com/apps

2. Click Create New App.

   Select Create New App to begin configuring your bot.

3. Choose From scratch.

   Choose the From scratch option for a custom app setup.

4. Give your app a name (e.g., “AI Assistant Bot”).

5. Select the Slack workspace where the bot should be installed.

6. Click Create App.

   Name the app and pick the workspace where it will run.

You now have a base Slack app ready for configuration.

---

2. Set Up OAuth & Permissions

This ensures your AI bot can read messages, post replies, access users, and interact with channels.

Add the required bot token scopes so the AI agent can read and post.

2.1 Add Required Scopes

Navigate to OAuth & Permissions → Scopes → Bot Token Scopes and add:

• chat:write — Send messages as the bot.
• channels:read — Read public channel metadata.
• groups:read — Read private channels where the bot is a member.
• im:read — Read direct messages addressed to the bot.
• users:read — Get user info (for mentions, names, etc).
• files:read — View shared files in conversations.
• channels:manage — Create/rename/manage channels (optional but recommended for admin bots).

Add each required bot scope before installing or updating the app.

2.2 Install or Reinstall the App

Scroll down to OAuth Tokens & Redirect URLs.

1. Click Install to Workspace.

   Install or reinstall the app after updating scopes.

2. Approve requested permissions.

   Approve requested permissions during installation.

3. Copy the Bot User OAuth Token (xoxb-…) — you need this in your backend.

   Copy the Bot User OAuth Token (xoxb) for backend configuration.

Note: If you change scopes later, Slack requires app reinstallation.

---

3. Enable Event Subscriptions

Slack events are how your bot receives messages, mentions, and interactions.

Steps:

1. Open Event Subscriptions in the left menu.

2. Toggle Enable Events.

3. Copy your request URL from the platform

   Enable events and paste your request URL so Slack can send notifications.

4. Enter your request URL.

5. Once validated, the URL status shows Verified

   Slack verifies the request URL before sending event payloads.

---

4. Subscribe to Bot Events

Your AI assistant must receive message events from channels, groups, and DMs.

Pick which bot events (mentions and messages) your app will receive.

Add the following Bot User Events:

• app_mention — When someone types @yourbot.
• message.channels — Messages in public channels (Bot must be a member).
• message.groups — Messages in private channels (Bot must be invited).
• message.im — Direct messages sent to the bot.

Click Save Changes

---

5. Configure App Home

App Home gives users a dedicated space to chat with your bot.

Steps:

1. Open App Home from the left side menu.

2. Ensure App Home is turned ON.

3. Enable the Messages Tab.

4. Check:

   Allow users to send Slash commands and messages from the messages tab.

This allows people to DM your bot directly inside the App Home interface.

Turn on App Home and the Messages tab to allow direct bot conversations.

---

6. Reinstall After Scope Changes

Slack shows this banner when any permission scope is modified:

You’ve changed the permission scopes your app uses. Please reinstall your app for these changes to take effect (and if your app is listed in the Slack Marketplace, you’ll need to resubmit it as well).

---

You're all set!

Your Slack app is fully configured—let's test it:

1. Reinstall the app to apply any new scopes.
2. Invite the bot to a channel.
3. Add the app in the channel and start asking to your Slack agent.
4. Mention the bot in a channel and confirm it replies (and threads).
5. Send a file to check file-based input handling.

Test your bot in App Home or channels after reinstalling and inviting it.