Interface Parameters
Pass one ofagent, team, or workflow to the Slack constructor.
| Parameter | Type | Default | Description |
|---|---|---|---|
agent | Optional[Agent] | None | Agno Agent instance. |
team | Optional[Team] | None | Agno Team instance. |
workflow | Optional[Workflow] | None | Agno Workflow 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_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). |
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 (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 |
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
Slack Guide
Sessions, threads, files, streaming, and troubleshooting.
Deploy Guide
Create a Slack App and configure step by step.
SlackTools Reference
Toolkit methods for messaging, search, and files.