Bidirectional Telegram integration for Paperclip. Push agent notifications to Telegram, receive bot commands, approve requests with inline buttons, and route forum topics to projects.

Built on the Paperclip plugin SDK and the domain event bridge (PR #909).

• Push notifications on issue created, issue done, approval requested, agent error, run lifecycle
• Bot commands: /status, /issues, /agents, /approve, /help, /connect, /connect-topic, /acp, /commands
• Inline buttons for approve/reject on approval notifications
• Inbound routing: reply to a notification in Telegram and it becomes an issue comment in Paperclip
• Per-company chat routing with /connect command
• Forum topic routing: map Telegram topics to Paperclip projects
• Daily digest: scheduled summary of agent activity
• MarkdownV2 formatting with automatic plain text fallback
• ACP bridge: /acp spawn, /acp status, /acp cancel, /acp close for managing agent sessions

• Agents call escalate_to_human tool when stuck (low confidence, user request, policy violation, unknown intent)
• Escalation posted to dedicated channel with conversation context, suggested reply, and confidence score
• Inline buttons: Send Suggested Reply, Reply, Override, Dismiss
• Configurable timeout with default actions (defer, auto_reply, close)
• Hold message sent to customer while waiting for human response
• Reply routing back to originating chat via native or ACP transport

• Multiple agents per thread (up to 5 configurable via MAX_AGENTS_PER_THREAD)
• @mention routing: address a specific agent by name in a multi-agent thread
• Reply-to routing: reply to an agent's message to route to that agent
• Fallback routing: most recently active agent receives unaddressed messages
• Handoff: agents call handoff_to_agent tool to transfer work, with optional human approval gate
• Discuss: agents call discuss_with_agent tool to start back-and-forth conversation loops
• Conversation loops with configurable max turns and human checkpoint pauses
• Stale loop detection (auto-pause when output repeats)
• Output sequencing so multi-agent responses don't interleave
• Native-first spawning: tries Paperclip agent sessions before falling back to ACP
• Auto-spawn on handoff/discuss if target agent isn't already in the thread

• Voice messages, audio, video notes, documents, and photos routed to agents
• Voice/audio transcription via Whisper API with transcription preview posted back
• Brief Agent: media sent to intake channels is forwarded to a configurable Brief Agent for triage
• Media in active agent threads is routed to the active session (native or ACP)

• /commands import <json> - import a multi-step workflow as a custom slash command
• /commands list - show all registered custom commands
• /commands run <name> [args] - execute a workflow
• /commands delete <name> - remove a custom command
• Custom commands invocable directly as /<name> (cannot override built-ins)
• Workflow step types: fetch_issue, invoke_agent, http_request, send_message, create_issue, wait_approval, set_state
• Template interpolation: {{arg0}}, {{args}}, {{prev.result}}, {{step_id.result}}
• Per-company command registry

• Agents call register_watch tool to set up condition-based monitors
• Watch conditions: gt, lt, eq, ne, contains, exists operators on entity fields
• Watches evaluate against issues, agents, or custom state-stored data
• Built-in templates: invoice-overdue, lead-stale
• Custom templates with {{field}} placeholder interpolation
• Rate limiting: configurable max suggestions per hour per company
• Deduplication: same watch+entity won't re-fire within a configurable window (default 24h)
• Scheduled job checks all watches periodically

1. Open Telegram and chat with @BotFather
2. Run /newbot and follow the prompts
3. Save the bot token

Send a message to your bot, then run:

curl "https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates"

Find the chat.id field in the response. For groups, the ID is a negative number.

npm install paperclip-plugin-telegram

Or register with your Paperclip instance directly:

curl -X POST http://127.0.0.1:3100/api/plugins/install \
  -H "Content-Type: application/json" \
  -d '{"packageName":"paperclip-plugin-telegram"}'

The bot token field requires a Paperclip secret reference (a UUID), not the raw token.

1. In Paperclip, go to Settings → Secrets → Create new secret
2. Paste your Telegram bot token as the secret value and save
3. Copy the UUID of the created secret
4. Use that UUID in the telegramBotTokenRef field below

Do the same for transcriptionApiKeyRef if you want Whisper transcription.

In your Paperclip instance settings, configure:

If using a group chat:

1. Add the bot to your Telegram group
2. Disable privacy mode via BotFather (/setprivacy -> Disable) if you want the bot to see all messages
3. Run /connect <company-name> in the group

When Paperclip events fire (issue created, approval needed, agent error), the plugin formats them as Telegram messages with MarkdownV2 and sends to the configured chat.

Approval notifications include inline Approve/Reject buttons. Clicking a button calls the Paperclip API directly and updates the message to show the resolution.

The bot registers commands with Telegram's command menu. Users can interact with Paperclip directly:

• /status - overview of agents and tasks
• /issues - list open issues
• /agents - list agents with status
• /approve <id> - approve a pending request
• /connect <company> - link this chat to a Paperclip company

When a user replies to a bot notification, the plugin looks up which Paperclip entity that notification was about and posts the reply as an issue comment. This turns Telegram threads into a natural conversation interface for Paperclip issues.

The telegramBotTokenRef and transcriptionApiKeyRef fields now require a Paperclip secret reference (a UUID), not the raw token value. If you previously entered your raw bot token in the field, follow these steps to migrate:

1. Go to Settings → Secrets → Create new secret
2. Paste your Telegram bot token as the secret value and save
3. Copy the resulting UUID
4. Open Plugin Settings for Telegram Bot and paste the UUID into "Telegram Bot Token"
5. Save and restart the plugin

The plugin will fail to activate if a raw token (non-UUID) is entered in the field.

pnpm install
pnpm build
pnpm typecheck

MIT

@MatB57 - Escalation channel concept, "Chat OS" vision for turning chat plugins into bidirectional agent command centers, and the HITL suggested-reply flow.

@leeknowsai - Worker bootstrap patterns adapted from the Discord plugin.

Inspired by OpenClaw's Telegram integration (grammY, bidirectional messaging, inline buttons) and adapted for the Paperclip plugin SDK.