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

# Slack Bot

> Create a Slack App, configure OAuth scopes and event subscriptions, and deploy an Agno agent.

```python slack_bot.py theme={null}
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIChat
from agno.os.app import AgentOS
from agno.os.interfaces.slack import Slack

agent_db = SqliteDb(session_table="agent_sessions", db_file="tmp/persistent_memory.db")

basic_agent = Agent(
    name="Basic Agent",
    model=OpenAIChat(id="gpt-4o"),
    db=agent_db,
    add_history_to_context=True,
    num_history_runs=3,
    add_datetime_to_context=True,
)

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

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

<Note>
  Install the dependency: `uv pip install 'agno[slack]'`
</Note>

## Setup

<Steps>
  <Step title="Create a Slack App">
    1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**
    2. Choose **From scratch**, give it a name, and select your workspace
    3. On the **Basic Information** page, copy the **Signing Secret**
  </Step>

  <Step title="Enable Agents & AI Apps">
    This is required for streaming task cards and suggested prompts.

    1. In the sidebar, click **Agents & AI Apps**
    2. Toggle **Agent or Assistant** to **On**
    3. Under **Suggested Prompts**, select **Dynamic**
    4. Click **Save**

    <Note>
      Enabling this automatically adds the `assistant:write` scope.
    </Note>
  </Step>

  <Step title="Add OAuth Scopes">
    1. In the sidebar, click **OAuth & Permissions**
    2. Under **Scopes > Bot Token Scopes**, add:

    | Scope               | Purpose                                   |
    | ------------------- | ----------------------------------------- |
    | `app_mentions:read` | Receive @mention events                   |
    | `assistant:write`   | Streaming (task cards, suggested prompts) |
    | `chat:write`        | Send messages and stream responses        |
    | `im:history`        | Read DM history for thread context        |
    | `files:read`        | Download files users send to the bot      |
    | `files:write`       | Upload response files (images, docs)      |

    <Tip>
      These are the minimum scopes for streaming. Add `channels:history`, `groups:history`, `users:read`, or `search:read` if your agent uses `SlackTools` for channel history, user lookup, or message search.
    </Tip>

    3. Click **Install to Workspace** and authorize the app
    4. Copy the **Bot User OAuth Token** (`xoxb-...`)
  </Step>

  <Step title="Set Environment Variables">
    ```bash theme={null}
    export SLACK_TOKEN="xoxb-your-bot-user-token"
    export SLACK_SIGNING_SECRET="your-signing-secret"
    ```

    Find these in your Slack App settings:

    * **Bot User OAuth Token**: OAuth & Permissions
    * **Signing Secret**: Basic Information > App Credentials
  </Step>

  <Step title="Subscribe to Events">
    1. In the sidebar, click **Event Subscriptions**

    2. Toggle **Enable Events** to **On**

    3. Set **Request URL** to your tunnel URL:
       ```
       https://<your-tunnel>/slack/events
       ```
       Your app must be running for Slack to verify the URL.

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

    | Event                      | Purpose                              |
    | -------------------------- | ------------------------------------ |
    | `app_mention`              | Respond to @mentions in channels     |
    | `message.im`               | Respond to direct messages           |
    | `assistant_thread_started` | Set suggested prompts on new threads |

    <Tip>
      Add `message.channels` and `message.groups` if you set `reply_to_mentions_only=False` and want the bot to respond to all channel messages.
    </Tip>

    5. Click **Save Changes**
    6. Go to **Install App** and click **Reinstall to Workspace**
  </Step>

  <Step title="Enable App Home">
    1. In the sidebar, click **App Home**
    2. Under **Show Tabs**, enable **Messages Tab**
    3. Check **Allow users to send Slash commands and messages from the messages tab**
  </Step>

  <Step title="Start a Tunnel">
    Slack needs a public HTTPS URL to deliver events:

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

    Copy the `https://` forwarding URL and paste it into the Event Subscriptions Request URL (Step 5). The free ngrok tier gives you a random subdomain that changes on restart.
  </Step>

  <Step title="Run the App">
    ```bash theme={null}
    python slack_bot.py
    ```

    DM the bot or @mention it in a channel to test.
  </Step>
</Steps>

<Warning>
  ngrok is for local development only. For production, see the [deployment templates](/deploy/templates).
</Warning>

## Scopes Reference

Add scopes based on the features your bot uses.

### Minimum (streaming bot that responds to mentions and DMs)

| Scope               | Required For                                           |
| ------------------- | ------------------------------------------------------ |
| `app_mentions:read` | Receive @mention events in channels                    |
| `assistant:write`   | Streaming task cards, suggested prompts, thread titles |
| `channels:read`     | Resolve channel names (called on every inbound event)  |
| `chat:write`        | Send messages and stream responses                     |
| `im:history`        | Read DM history for thread context                     |

### File handling

| Scope         | Required For                                                    |
| ------------- | --------------------------------------------------------------- |
| `files:read`  | Download files users attach to messages                         |
| `files:write` | Upload images, audio, video, and files generated by agent tools |

### SlackTools methods

| Scope                | Required For                                                |
| -------------------- | ----------------------------------------------------------- |
| `channels:read`      | `list_channels()`, `get_channel_info()`                     |
| `channels:history`   | `get_channel_history()`, `get_thread()` in public channels  |
| `groups:read`        | `list_channels()` for private channels                      |
| `groups:history`     | `get_channel_history()`, `get_thread()` in private channels |
| `search:read`        | `search_messages()` (requires user token)                   |
| `search:read.public` | `search_workspace()` messages and channels                  |
| `search:read.files`  | `search_workspace()` files                                  |
| `search:read.users`  | `search_workspace()` users                                  |
| `users:read`         | `list_users()`, `get_user_info()`                           |
| `users:read.email`   | `get_user_info()` with email field                          |

### Other features

| Scope              | Required For                                        |
| ------------------ | --------------------------------------------------- |
| `users:read`       | `resolve_user_identity=True` on the Slack interface |
| `users:read.email` | `resolve_user_identity=True` with email lookup      |
| `channels:history` | `reply_to_mentions_only=False` in public channels   |
| `groups:history`   | `reply_to_mentions_only=False` in private channels  |

### Event subscriptions

| Event                      | Required For                                                             |
| -------------------------- | ------------------------------------------------------------------------ |
| `app_mention`              | Respond to @mentions in channels                                         |
| `message.im`               | Respond to direct messages                                               |
| `assistant_thread_started` | Set suggested prompts on new threads                                     |
| `message.channels`         | Respond to all public channel messages (`reply_to_mentions_only=False`)  |
| `message.groups`           | Respond to all private channel messages (`reply_to_mentions_only=False`) |

## Developer Resources

<CardGroup cols={2}>
  <Card title="Slack Interface" icon="book" href="/agent-os/interfaces/slack/introduction">
    Streaming, sessions, file handling, and behavior details.
  </Card>

  <Card title="Interface Reference" icon="square-sliders" href="/agent-os/interfaces/slack/reference">
    All parameters, endpoints, and event handling.
  </Card>

  <Card title="SlackTools" icon="wrench" href="/tools/toolkits/social/slack">
    Give agents outbound Slack actions: messaging, search, files.
  </Card>

  <Card title="Deployment Templates" icon="server" href="/deploy/templates">
    Production deployment guides for AWS, GCP, and Docker.
  </Card>
</CardGroup>