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.

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.

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

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

Quick start with agents, teams, and workflows.

Setup Guide

Create a Slack App with the manifest.

SlackTools

Toolkit methods for messaging, search, and files.