Bot Connectors

Architecture

┌──────────────┐     ┌──────────────┐
│   Telegram   │     │   Discord    │
│   Message    │     │   Message    │
└──────┬───────┘     └──────┬───────┘
       │                    │
       ▼                    ▼
┌──────────────┐     ┌──────────────┐
│  Telegram    │     │   Discord    │
│  Connector   │     │  Connector   │
│              │     │              │
│ - Streaming  │     │ - Slash cmds │
│ - Ack emoji  │     │ - Ack emoji  │
│ - Voice      │     │ - Typing     │
│ - /new /init │     │ - /new /chat │
└──────┬───────┘     └──────┬───────┘
       │                    │
       └────────┬───────────┘
                │
       ┌────────▼────────┐
       │  BotConnector   │
       │    (base.py)    │
       │                 │
       │ - Per-chat lock │
       │ - Trust levels  │
       │ - User pairing  │
       │ - Init flow     │
       │ - Group history │
       │ - Split response│
       └────────┬────────┘
                │
       ┌────────▼────────┐
       │   Orchestrator  │
       │  (streaming)    │
       └─────────────────┘
                    

Source Files

Configuration

Bot connectors are configured in vault/.parachute/bots.yaml:

telegram:
  enabled: true
  bot_token: "123456:ABC-DEF..."
  allowed_users:
    - 12345678           # Telegram user IDs
  dm_trust_level: vault
  group_trust_level: sandboxed
  group_mention_mode: mention_only
  ack_emoji: "👀"

discord:
  enabled: true
  bot_token: "MTIzNDU2..."
  allowed_users:
    - "987654321"        # Discord user IDs (strings)
  dm_trust_level: vault
  group_trust_level: sandboxed
  group_mention_mode: mention_only
  ack_emoji: "👀"

Trust Levels per Platform

Features

Session Lifecycle

User sends message
        │
        ▼
┌───────────────────┐
│ is_user_allowed?  │──── No ──▶ handle_unknown_user()
└───────┬───────────┘             → Create pairing_request
        │ Yes                     → Create pending session
        ▼                         → "Request sent to owner"
┌───────────────────┐
│ get_or_create_    │
│ session()         │
│                   │
│ Find by bot link  │
│ or create new     │
└───────┬───────────┘
        │
        ▼
┌───────────────────┐
│ is_session_       │──── No ──▶ Nudge: "Configure in app"
│ initialized?      │             (max 2 nudges, then silent)
└───────┬───────────┘
        │ Yes
        ▼
┌───────────────────┐
│ Check response    │
│ mode (per-session)│──── mention_only + no mention ──▶ ignore
└───────┬───────────┘
        │
        ▼
┌───────────────────┐
│ Add ack reaction  │
│ Inject group      │
│ history if group  │
│ Acquire chat lock │
│ Route to          │
│ orchestrator      │
│ Stream/send       │
│ Remove ack        │
└───────────────────┘
                    

Telegram Connector

Commands

Streaming Implementation

Telegram streams responses by editing a "draft" message as tokens arrive:

1. Send initial empty message (or first chunk)
2. Accumulate tokens from orchestrator SSE events
3. Every ~30 tokens, edit the message with accumulated text
4. Format with claude_to_telegram() (markdown adjustments for Telegram HTML)
5. On completion, send final edit with full response

Group Mention Detection

Uses Telegram's entity system for reliable mention detection (not string matching). Checks MessageEntity.MENTION and MessageEntity.TEXT_MENTION types against the bot's username.

Discord Connector

Slash Commands

Response Handling

Discord doesn't stream mid-message edits like Telegram. Instead:

1. Show typing indicator while processing
2. Collect full response from orchestrator
3. Format with claude_to_discord()
4. Split at 2000-char limit (Discord max), send as reply chain

Group History

Discord has channel.history() API, so history is fetched on-demand rather than buffered. Same XML tag injection and name sanitization as Telegram.

Message Formatting

message_formatter.py converts Claude's markdown output to platform-compatible formats:

Long responses are split at paragraph boundaries using BotConnector.split_response(), preserving code blocks across chunks.

User Pairing Flow

When an unknown user messages the bot:

1. Bot creates a pairing_request in the database
2. Bot creates a "pending" session visible in the Parachute app chat list
3. Bot replies: "Your request has been sent to the owner"
4. Owner sees request in app → approves with trust level
5. POST /api/bots/pairing/{id}/approve triggers approval
6. Connector adds user to allowed list + sends "You've been approved!" message
7. Subsequent messages from user are processed normally

Per-user trust level overrides are cached in-memory and looked up from the approved pairing request.

Security Considerations

• Allowlist enforcement: Only allowed_users from bots.yaml can trigger AI responses
• Prompt injection resistance: Group messages are wrapped in <group_context> XML tags; display names are sanitized (brackets, angle brackets, newlines stripped, max 50 chars)
• Trust isolation: Group chats default to sandboxed (Docker container). DMs default to vault.
• Per-chat locks: Prevent race conditions from rapid messages in the same chat
• Bot tokens: Stored in bots.yaml which should be protected (not version-controlled)

Management API

Connectors can be managed through the API or the Parachute app Settings screen:

# Check status
GET /api/bots/status

# Start/stop connectors
POST /api/bots/telegram/start
POST /api/bots/telegram/stop

# View and manage pairing requests
GET /api/bots/pairing
POST /api/bots/pairing/{id}/approve  {"trust_level": "vault"}
POST /api/bots/pairing/{id}/deny

# Update configuration
GET /api/bots/config
PUT /api/bots/config  {...}

Connectors auto-start on server boot if enabled: true in bots.yaml. Errors during auto-start are logged but never crash the server.

Next Steps