> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Create a Slack App and connect it to your Agno agent.

To connect an agent to Slack, you need three pieces in place:

1. **A public endpoint** for Slack to send events to. In development, use ngrok to forward Slack traffic to your local AgentOS server.

2. **A Slack app** that represents your agent in the workspace. This is what users see under **Apps** in Slack, with its own name, icon, and permissions.

3. **Credentials** so your agent can talk to Slack and verify incoming requests. You'll use a bot token for Slack API calls and a signing secret for webhook verification.

After setup, Slack events follow this path:

```
Slack  →  https://YOUR-URL/slack/events  →  AgentOS  →  Agent
```

The guide below walks through the setup step by step.

> [!NOTE]
>
> Install dependencies first: `uv pip install 'agno[os,slack]' openai`

## 1. Expose your local server

Slack needs a public HTTPS URL for event callbacks. For local development, start an ngrok tunnel to your AgentOS server:

```bash theme={null}
ngrok http 7777
```

> [!TIP]
>
> You now have a public HTTPS endpoint. Copy the forwarding URL, since the app you create next will point at it.

> [!WARNING]
>
> **ngrok generates a new URL on each restart.** For production, use a stable domain instead: deploy with a [Starter template](https://agno-v2.mintlify.site/deploy/introduction.md).

## 2. Create the Slack app

Create a Slack app for your agent and configure the permissions and events it needs.

**Manifest**

The manifest is the quickest setup path. It pre-configures the scopes, events, and settings needed for DMs, @mentions, and [Human-in-the-Loop](https://agno-v2.mintlify.site/hitl/overview.md) interactions.

1. Download [manifest.json](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/os/interfaces/slack/manifest.json) and replace `https://YOUR-URL` with your ngrok URL
2. Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From a manifest**
3. Select your workspace, choose **JSON**, and paste the manifest contents
4. Click **Next**, review the summary, then click **Create**

> [!TIP]
>
> Your Slack app now has the required scopes and event subscriptions.

**Manual**

This path configures each setting individually. Use it when you need custom scopes or want to understand what the manifest abstracts. Each area below maps to a page in the Slack app dashboard.

**1. Create the app**

1. Go to [api.slack.com/apps](https://api.slack.com/apps)
2. Click **Create New App** → **From scratch**
3. Name it (e.g., "My Agent"), select your workspace, then click **Create App**

**2. Configure App Home**

App Home is your agent's surface in Slack. Users find it under **Apps** and start conversations there.

1. Click **App Home** in the sidebar
2. Under **Show Tabs**, enable **Messages Tab**
3. Check **Allow users to send Slash commands and messages from the messages tab**

**3. Enable Agents & AI Apps**

Streaming responses and task cards use Slack's assistant UI, which has its own feature toggle.

1. Click **Agents & AI Apps** in the sidebar
2. Toggle the feature **On**

Without this, users see a spinner until the full response is ready (see [Streaming](https://agno-v2.mintlify.site/agent-os/interfaces/slack/features.md#streaming)).

**4. Add OAuth scopes**

Scopes are the permissions your app requests, and each one grants a single capability like reading messages, sending replies, or accessing files.

Go to **OAuth & Permissions** → **Scopes** → **Bot Token Scopes** and add:

| Scope | Purpose | Required? |
| - | - | - |
| `app_mentions:read` | See @mentions | Yes |
| `chat:write` | Send messages | Yes |
| `im:history` | Read DM history | Yes |
| `assistant:write` | Slack's assistant UI with streaming | Yes |
| `channels:read` | See public channel membership | Yes |
| `channels:history` | Read public channel history | Recommended |
| `groups:read` | See private channel membership | Optional |
| `groups:history` | Read private channel history | Optional |
| `files:read` | Access shared files | Optional |
| `files:write` | Upload files | Optional |
| `users:read` | Look up user profiles | Optional |
| `users:read.email` | Look up user emails | Optional |

> [!TIP]
>
> Start with the required scopes and add optional ones later, keeping in mind that each change needs a reinstall. Slack's [scopes reference](https://docs.slack.dev/reference/scopes/) documents the full catalog.

**5. Subscribe to events**

Events tell Slack when to call your webhook. Go to **Event Subscriptions**:

1. Toggle **Enable Events** to **On**
2. Enter **Request URL**: `https://YOUR-NGROK-URL/slack/events`
3. Slack sends a verification challenge to that URL

> [!WARNING]
>
> **The verification challenge needs a live endpoint.** If it fails, complete the [Connect your agent](#4-connect-your-agent) step first, then return and retry.

Under **Subscribe to bot events**, add:

| Event | Fires when |
| - | - |
| `app_mention` | Someone @mentions the agent |
| `message.im` | Someone DMs the agent |
| `assistant_thread_started` | Someone opens a thread with the agent |

To also receive channel messages, add `message.channels` and `message.groups` (see [Respond to all channel messages](#respond-to-all-channel-messages)).

**6. Enable interactivity**

[Human-in-the-Loop](https://agno-v2.mintlify.site/hitl/overview.md) features (confirmation buttons, input forms) require interactivity. This routes button clicks and form submissions to your agent.

1. Click **Interactivity & Shortcuts** in the sidebar
2. Toggle **Interactivity** to **On**
3. Enter **Request URL**: `https://YOUR-NGROK-URL/slack/interactions`

> [!TIP]
>
> The manual configuration now matches what the manifest sets up automatically.

## 3. Install and collect credentials

The last remaining problem is authentication, and installing the app to your workspace generates both credentials you need.

1. Click **Install App** in the sidebar
2. Click **Install to Workspace**, review permissions, then click **Allow**
3. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
4. Go to **Basic Information** → **App Credentials** and copy the **Signing Secret**

Export them so your code can authenticate:

```bash theme={null}
export SLACK_TOKEN="xoxb-..."           # Bot User OAuth Token
export SLACK_SIGNING_SECRET="..."       # From Basic Information → App Credentials
```

> [!TIP]
>
> Slack-side setup is complete: the app exists, it points at your URL, and you hold its credentials.

## 4. Connect your agent

With all three problems solved, the only thing left is to connect the agent itself:

```python app.py theme={null}
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.os.app import AgentOS
from agno.os.interfaces.slack import Slack

agent = Agent(name="My Agent", model=OpenAIResponses(id="gpt-5.4"))

agent_os = AgentOS(
    agents=[agent],
    interfaces=[Slack(agent=agent)],
)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="app:app", reload=True)
```

```bash theme={null}
python app.py
```

AgentOS mounts the Slack interface at `/slack/events`, the same path your webhook points at. Events from Slack now reach your agent.

## 5. Test in Slack

Once the agent is running, verify everything works by sending it a message. The quickest check is a direct message: find your agent under **Apps** in Slack and say hello.

To test in a channel, invite the agent and then mention it:

```
/invite @MyAgent
@MyAgent hello!
```

Each thread keeps its own conversation, so follow-up messages in the same thread don't need another @mention.

> [!TIP]
>
> If the agent replies, events are flowing from Slack through AgentOS to your agent. Setup is complete.

## Customization

The five steps above cover the standard setup. Two adjustments come up often enough to walk through here.

> [!WARNING]
>
> **Scope and event changes require reinstalling.** Go to **Install App** → **Reinstall to Workspace** after any change.

### Respond to all channel messages

By default, the agent only responds to @mentions and DMs. To respond to every message in channels it's in:

1. In **Event Subscriptions**, add `message.channels` and `message.groups` events
2. Go to **Install App** → **Reinstall to Workspace**
3. Update your code:

```python theme={null}
Slack(agent=agent, reply_to_mentions_only=False)
```

See [Response control](https://agno-v2.mintlify.site/agent-os/interfaces/slack/features.md#response-control) for how this changes the agent's behavior.

### Add search tools

If your agent uses `SlackTools.search_workspace()`, the app needs three additional scopes:

* `search:read.public`
* `search:read.files`
* `search:read.users`

Add them under **OAuth & Permissions**, then reinstall.

## Next steps

Once your agent is responding in Slack, continue with the deeper interface guides.

> **[Features](https://agno-v2.mintlify.site/agent-os/interfaces/slack/features.md)**
>
> Sessions, files, streaming, and more

> **[Human-in-the-Loop](https://agno-v2.mintlify.site/agent-os/interfaces/slack/hitl.md)**
>
> Pause for approval before taking actions

> **[Reference](https://agno-v2.mintlify.site/agent-os/interfaces/slack/reference.md)**
>
> All parameters, scopes, and events


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.