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

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

```bash theme={null}
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.

```python theme={null}
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`.

```python theme={null}
from upsonic import AutonomousAgent
from upsonic.interfaces import InterfaceManager, SlackInterface

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-6",
    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](/concepts/agents/advanced/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:

```python theme={null}
import os
from upsonic import Agent
from upsonic.interfaces import InterfaceManager, SlackInterface, InterfaceMode

agent = Agent(
    model="anthropic/claude-sonnet-4-6",
    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.


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