> ## 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.

# Slack Reference

> Interface parameters, endpoints, event handling, and OAuth scopes for the Slack interface.

## Interface Parameters

Pass one of `agent`, `team`, or `workflow` to the `Slack` constructor.

```python theme={null}
from agno.os.interfaces.slack import Slack

Slack(agent=my_agent, streaming=True, prefix="/slack")
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `agent` | `Optional[Union[Agent, RemoteAgent]]` | `None` | Agno `Agent` or `RemoteAgent` instance. |
| `team` | `Optional[Union[Team, RemoteTeam]]` | `None` | Agno `Team` or `RemoteTeam` instance. |
| `workflow` | `Optional[Union[Workflow, RemoteWorkflow]]` | `None` | Agno `Workflow` or `RemoteWorkflow` instance. |
| `prefix` | `str` | `"/slack"` | URL prefix for Slack endpoints (e.g., `/slack` means events arrive at `/slack/events`). |
| `tags` | `Optional[List[str]]` | `None` | FastAPI route tags for API documentation. Defaults to `["Slack"]`. |
| `reply_to_mentions_only` | `bool` | `True` | When `True` (default), the bot responds to @mentions in channels and all DMs. When `False`, responds to all channel messages. |
| `token` | `Optional[str]` | `None` | Bot token. Falls back to `SLACK_TOKEN` environment variable. |
| `signing_secret` | `Optional[str]` | `None` | Slack app signing secret. Falls back to `SLACK_SIGNING_SECRET` environment variable. |
| `streaming` | `bool` | `True` | Enable real-time streaming with task cards and live text updates. |
| `loading_messages` | `Optional[List[str]]` | `None` | Status messages shown while the agent processes. Rotated automatically by Slack. |
| `task_display_mode` | `str` | `"plan"` | How task cards render in the streaming UI. `"plan"` shows a collapsible plan block. |
| `loading_text` | `str` | `"Thinking..."` | Status text shown while the agent starts processing. |
| `suggested_prompts` | `Optional[List[Dict[str, str]]]` | `None` | Prompts shown when a user opens a new thread. Each dict has `title` and `message` keys. Defaults to Help and Search prompts. |
| `ssl` | `Optional[SSLContext]` | `None` | SSL context for the Slack WebClient. |
| `buffer_size` | `int` | `100` | Characters to buffer before flushing a streaming update. |
| `max_file_size` | `int` | `1073741824` | Maximum file size in bytes for uploads and downloads (default 1 GB). |
| `resolve_user_identity` | `bool` | `False` | Look up each user's email and display name via the Slack `users.info` API. When enabled, the agent receives the user's email as `user_id` instead of their Slack ID, and `metadata` includes `user_name` and `user_id` (the resolved email). |

## Endpoints

Available at the `/slack` prefix (customizable with `prefix`).

### `POST {prefix}/events`

Receives all Slack events (URL verification, messages, app mentions, thread starts).

| Status | Description |
| - | - |
| **200** | Event acknowledged. Processing happens in the background so Slack gets a response within 3 seconds. |
| **400** | Missing `X-Slack-Request-Timestamp` or `X-Slack-Signature` headers. |
| **403** | Invalid Slack signing signature. |
| **500** | `SLACK_SIGNING_SECRET` is not set (checked on each request, not at startup). |

### `POST {prefix}/interactions`

Handles Slack interactive components for Human-in-the-Loop (HITL) features: button clicks, form submissions, and approval/denial actions.

| Status | Description |
| - | - |
| **200** | Interaction acknowledged. Processing happens in the background. |
| **400** | Missing Slack headers or malformed payload. |
| **403** | Invalid Slack signing signature. |

> [!WARNING]
>
> HITL features require this endpoint. Configure **Interactivity & Shortcuts** in your Slack App settings and set the Request URL to `{your-url}{prefix}/interactions`.

### Built-in Event Handling

| Event | Behavior |
| - | - |
| URL verification | Echoes the `challenge` field back to Slack during app setup. |
| `assistant_thread_started` | Sets `suggested_prompts` on new threads (streaming mode only). |
| Retry deduplication | Events with `X-Slack-Retry-Num` are acknowledged without reprocessing. The original event is already being processed in the background. |
| Bot self-loop prevention | Events with `bot_id` or subtypes `bot_message`, `message_changed`, `message_deleted`, and other bot lifecycle events are ignored. |

## OAuth Scopes

Add scopes in your Slack App under **OAuth & Permissions > Bot Token Scopes**.

### Minimum (streaming bot)

| 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 and IDs (called on every inbound event) |
| `chat:write` | Send messages and stream responses |
| `im:history` | Read DM history for thread context |

> [!NOTE]
>
> All five scopes above are required for a functional streaming bot. Missing `app_mentions:read` means the bot won't receive @mentions; missing `channels:read` causes channel name resolution to fail silently.

### 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 |
| `chat:write` | `send_message()`, `send_message_thread()` |
| `files:read` | `download_file()`, `download_file_bytes()` |
| `files:write` | `upload_file()` |
| `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 |

### Feature-Specific

| 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

Subscribe to events under **Event Subscriptions > Subscribe to bot events**.

| 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

> **[Overview](https://agno-v2.mintlify.site/agent-os/interfaces/slack/introduction.md)**
>
> Quick start with agents, teams, and workflows.

> **[Setup Guide](https://agno-v2.mintlify.site/agent-os/interfaces/slack/setup.md)**
>
> Create a Slack App with the manifest.

> **[SlackTools](https://agno-v2.mintlify.site/tools/toolkits/social/slack.md)**
>
> Toolkit methods for messaging, search, and files.


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