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