# IM Channel Connections

DeerFlow supports user-owned IM channel connections for Telegram, Slack, and Discord. A logged-in user connects a provider from the frontend, and incoming IM messages run under that DeerFlow user account instead of the raw platform user id.

## Configuration

Enable the top-level `channel_connections` block in `config.yaml`:

```yaml
channel_connections:
  enabled: true
  public_base_url: https://deerflow.example.com
  encryption_key: $DEER_FLOW_CHANNEL_CONNECTIONS_KEY

  telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN
    bot_username: $TELEGRAM_BOT_USERNAME
    webhook_secret: $TELEGRAM_WEBHOOK_SECRET

  slack:
    enabled: true
    client_id: $SLACK_CLIENT_ID
    client_secret: $SLACK_CLIENT_SECRET
    signing_secret: $SLACK_SIGNING_SECRET
    event_delivery: http

  discord:
    enabled: true
    client_id: $DISCORD_CLIENT_ID
    client_secret: $DISCORD_CLIENT_SECRET
    bot_token: $DISCORD_BOT_TOKEN
    permissions: "274877975552"
```

`public_base_url` must be the externally reachable HTTPS origin used by provider callbacks and webhooks. `encryption_key` encrypts provider tokens at rest with Fernet. Keep it stable; v1 does not support transparent key rotation, so changing it requires users to reconnect.

## Frontend Flow

The workspace sidebar shows a Channels group with Telegram, Slack, and Discord. Settings > Channels exposes the management surface for connect, disconnect, and reconnect. Browser state-changing calls use the existing CSRF-aware frontend fetch wrapper.

## Provider Setup

Telegram:

- Register a bot with BotFather.
- Configure the bot username, bot token, and a random webhook secret.
- Users connect with a deep link: `https://t.me/<bot_username>?start=<state>`.
- Production webhook path: `POST /api/channels/webhooks/telegram`, protected by `X-Telegram-Bot-Api-Secret-Token`.
- Local/self-hosted long polling still works through the existing Telegram channel worker.

Slack:

- Create a Slack app with OAuth V2.
- Redirect URL: `https://<public_base_url>/api/channels/slack/callback`.
- Event request URL: `https://<public_base_url>/api/channels/webhooks/slack/events`.
- Required signing secret: Slack's request signing secret, not the deprecated verification token.
- Suggested MVP bot scopes: `app_mentions:read`, `chat:write`, `channels:history`, `channels:read`.
- Slack events are signature-verified, deduplicated by `event_id`, and then routed to a matching user connection.

Discord:

- Create a Discord application and bot.
- Redirect URL: `https://<public_base_url>/api/channels/discord/callback`.
- DeerFlow starts OAuth with `identify guilds bot applications.commands` and the configured bot permissions.
- The Discord Gateway is still handled by `discord.py`; message content may require the privileged Message Content Intent depending on your bot setup.

## Runtime Model

Connection records live in SQL tables under `deerflow.persistence.channel_connections`:

- `channel_connections`: owner user, provider identity, workspace/guild/team, status, metadata.
- `channel_credentials`: encrypted access/refresh/bot tokens.
- `channel_oauth_states`: one-time OAuth/deep-link states.
- `channel_conversations`: connection-scoped IM conversation to DeerFlow thread mapping.
- `channel_webhook_deliveries`: provider webhook dedupe records.

Incoming messages that resolve to a connection carry `connection_id`, `owner_user_id`, and `workspace_id`. `ChannelManager` uses `owner_user_id` as the DeerFlow run user id and preserves the platform user id as `channel_user_id`. Legacy operator-owned channels keep the existing JSON `ChannelStore` behavior when no `connection_id` is present.

## Security Notes

- OAuth state tokens are one-time and short-lived.
- Provider tokens are never returned from browser APIs.
- Public callback/webhook routes bypass cookie auth only because they validate provider state/signatures/secrets themselves.
- Slack and Telegram webhooks skip CSRF because they are called by providers, not browsers.
- Logs should never include access tokens, refresh tokens, bot tokens, OAuth codes, or raw signed webhook bodies.