Slack

Host agents as Slack applications

Use the Slack interface to serve Agents via Slack. It mounts webhook routes on a FastAPI app and sends responses back to Slack channels and direct messages.

Installation

Install the Slack interface dependencies:

uv pip install "upsonic[slack-interface]"

Setup

Required environment variables:

• SLACK_SIGNING_SECRET (for request signature validation)

• SLACK_TOKEN (Bot User OAuth Token, required by SlackTools for sending messages)

• Optional: SLACK_VERIFICATION_TOKEN

Operating Modes

• TASK (default) – Each message is processed as an independent task; no conversation history. Best for simple Q&A and one-off queries.
• CHAT – Messages from the same user share a conversation session. The agent remembers context. Best for multi-turn assistants and support bots.

Streaming

Set stream=True to progressively update the Slack message as tokens arrive from the agent. The initial message is posted immediately and then edited in-place as new chunks are generated. Works in both TASK and CHAT modes.

from upsonic import Agent
from upsonic.interfaces import InterfaceManager, SlackInterface

agent = Agent(
    model="openai/gpt-4o-mini",
    name="SlackBot",
)

slack = SlackInterface(
    agent=agent,
    mode="chat",
    stream=True,
)

manager = InterfaceManager(interfaces=[slack])

if __name__ == "__main__":
    manager.serve(host="0.0.0.0", port=8000)

Heartbeat

When used with an AutonomousAgent that has heartbeat=True, the interface periodically sends the agent’s heartbeat_message to the agent, then posts the response to Slack.

The target channel is resolved automatically from the first incoming message. You can also set it explicitly via heartbeat_channel.

from upsonic import AutonomousAgent
from upsonic.interfaces import InterfaceManager, SlackInterface

agent = AutonomousAgent(
    model="openai/gpt-4o-mini",
    name="SlackBot",
    heartbeat=True,
    heartbeat_period=30,
    heartbeat_message="Summarize any new updates.",
)

slack = SlackInterface(
    agent=agent,
    mode="chat",
    # heartbeat_channel="C01ABC123",  # optional explicit override
)

manager = InterfaceManager(interfaces=[slack])

if __name__ == "__main__":
    manager.serve(host="0.0.0.0", port=8000)

Reset Command (CHAT mode only)

In CHAT mode, users can clear their conversation by sending the reset command (e.g. /reset) as a message. Configure it with reset_command; set to None to disable.

If the agent has a workspace configured, the reset command will also trigger a dynamic greeting message based on the workspace configuration. See Workspace for details.

Access Control (Whitelist)

Pass allowed_user_ids (list of Slack user IDs, e.g. ["U01ABC123"]). Only those users are processed; others receive “This operation not allowed”. Omit allowed_user_ids (or set None) to allow all users.

Example Usage

Create an agent, expose it with the SlackInterface interface, and serve via InterfaceManager. Example with CHAT mode, reset command, and optional whitelist:

import os
from upsonic import Agent
from upsonic.interfaces import InterfaceManager, SlackInterface, InterfaceMode

agent = Agent(
    model="openai/gpt-4o-mini",
    name="SlackBot",
)

slack = SlackInterface(
    agent=agent,
    reply_to_mentions_only=True,
    name="Slack",
    mode=InterfaceMode.CHAT,
    reset_command="/reset",
    allowed_user_ids=["U0966K32DQV"],
)

manager = InterfaceManager(interfaces=[slack])

if __name__ == "__main__":
    manager.serve(host="0.0.0.0", port=8000, reload=False)

Core Components

• SlackInterface (interface): Wraps an Upsonic Agent for Slack via FastAPI.

• InterfaceManager.serve: Serves the FastAPI app using Uvicorn.

SlackInterface Interface

Main entry point for Upsonic Slack applications.

Initialization Parameters

Parameter	Type	Default	Description
agent	Agent	Required	Upsonic Agent instance.
signing_secret	Optional[str]	None	Slack signing secret (or set SLACK_SIGNING_SECRET).
verification_token	Optional[str]	None	Slack verification token (or set SLACK_VERIFICATION_TOKEN).
name	str	"Slack"	Interface name.
reply_to_mentions_only	bool	True	Whether to only reply to @mentions and DMs.
mode	Union[InterfaceMode, str]	InterfaceMode.TASK	TASK or CHAT.
reset_command	Optional[str]	"/reset"	Message text that resets chat session (CHAT mode). Set None to disable.
storage	Optional[Storage]	None	Storage backend for chat sessions (CHAT mode).
allowed_user_ids	Optional[List[str]]	None	Whitelist of Slack user IDs (e.g. "U01ABC123"). None = allow all.
stream	bool	False	Stream agent responses by progressively updating the message.
heartbeat_channel	Optional[str]	None	Explicit Slack channel ID for heartbeat delivery. Auto-detected from first incoming message if omitted.

Key Methods

Method	Parameters	Return Type	Description
attach_routes	None	APIRouter	Returns the FastAPI router and attaches endpoints.
is_user_allowed	user_id: str	bool	Whether the user is in the whitelist (or whitelist disabled).

Endpoints

Mounted under the /slack prefix:

POST /slack/events

• Receives Slack events and messages.

• Validates signature (X-Slack-Signature and X-Slack-Request-Timestamp).

• Handles URL verification challenge for webhook setup.

• Processes app_mention and message events via the agent.

• Sends replies in threads or directly in channels/DMs.

• Responses: 200 {"status": "ok"} for events, 200 {"challenge": "..."} for URL verification, 400 missing headers, 403 invalid signature, 500 errors.

GET /slack/health

• Health/status of the interface.