paperclip-plugin-telegram

Bidirectional Telegram integration for Paperclip. Push agent notifications to Telegram, receive bot commands, approve requests with inline buttons, gather community signals, run multi-agent sessions in threads, process media attachments, register custom commands, and deploy proactive agent suggestions.

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

Why this exists

Multiple Paperclip users asked for notifications on the same day the plugin system shipped (2026-03-14):

"is there a way to have codex/claude check paperclip to see when tasks are done without me prompting it?" - @Choose Liberty, Discord #dev

"basically to have it 'let me know when its done'" - @Choose Liberty, Discord #dev

"can claude code check paperclip to see when tasks are done" - @Nascozz, Discord #dev

@dotta (maintainer) responded: "we're also adding issue-changed hooks for plugins so when that lands someone could [make notifications]." The event bridge (PR #909) shipped that same day. @Ryze said "Really excited by the plugins. I had developed a custom plugin bridge that I will now deprecate and migrate over to the new supported plugin system."

This is that plugin.

What it does

Notifications (MarkdownV2 with plain text fallback)

• Issue created - Title, description, status, priority, assignee, project fields, and a "View Issue" link
• Issue done - Completion confirmation with status fields
• Approval requested - Interactive Approve and Reject inline buttons. Click to act without leaving Telegram.
• Agent error - Error message with warning indicator and human-readable agent label (the full agent ID is kept in a metadata line for correlation)
• Agent run started/finished - Optional lifecycle notifications, disabled by default to avoid chat spam

Interactive approvals

• Approve/reject inline buttons on every approval notification
• Clicking a button calls the Paperclip API and updates the Telegram message inline
• Callback query acknowledgment with result text

Per-type chat routing

• approvalsChatId - Dedicated chat for approval notifications
• approvalsTopicId - Dedicated forum topic for approval notifications
• errorsChatId - Dedicated chat for agent errors
• errorsTopicId - Dedicated forum topic for agent errors
• digestChatId - Dedicated chat for digest notifications
• digestTopicId - Dedicated forum topic for digest notifications
• escalationChatId - Dedicated chat for agent escalations
• Falls back to defaultChatId when per-type chats aren't configured
• Per-company overrides via /connect

Bot commands

• /status - Show active agents and recent completions
• /issues - List open issues
• /agents - List agents with status indicators
• /approve <id> - Approve a pending approval
• /help - Display all available commands
• /connect <company> - Link this chat to a Paperclip company
• /connect_topic <project-name> [topic-id] - Map a forum topic to an existing Paperclip project
• /topics list - Show forum topic mappings for this chat
• /topics remove <project-name> - Remove one forum topic mapping
• /topics clear - Remove all forum topic mappings for this chat
• /acp spawn <agent> - Start a new agent session in the current thread
• /acp status - Check ACP session status
• /acp cancel - Cancel a running ACP session
• /acp close - Close a completed ACP session
• /commands import <json> - Import a workflow command
• /commands list - List registered workflow commands
• /commands run <name> [args] - Execute a workflow command
• /commands delete <name> - Delete a workflow command

Phase 1: HITL Escalation

• 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

Phase 2: Multi-Agent Group Threads

• Multiple agents per thread (up to 5 configurable via maxAgentsPerThread)
• @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

Phase 3: Media-to-Task Pipeline

• 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)

Phase 4: Custom Workflow Commands

• /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

Phase 5: Proactive Agent Suggestions

• 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

Reply routing

• Reply to any bot notification to route your message back to Paperclip
• Replies to issue notifications create issue comments automatically
• Replies to escalation notifications resolve the escalation as a human reply
• Enable/disable with enableInbound config toggle (default: true)

Daily digest

• Configurable digest summaries posted to your Telegram chats
• Modes: daily (once), bidaily (twice), tridaily (three times per day)
• Configure via the digestMode config setting
• Includes: tasks completed/created, active agents, in-progress/review/blocked issues

Forum topic routing

• Map Telegram forum topics to existing Paperclip projects via /connect_topic
• Manage mappings with /topics list, /topics remove <project-name>, and /topics clear
• Notifications for a project are routed to its mapped topic
• Requires a group with forum topics enabled

Notification topic routing

• approvalsTopicId routes approval notifications to a dedicated forum topic.
• errorsTopicId routes agent error notifications to a dedicated forum topic.
• digestTopicId routes daily/bidaily/tridaily digest notifications to a dedicated forum topic.
• If a topic ID is empty, the plugin keeps its existing behavior. Digest messages in forum groups fall back to the General topic.
• onlyNotifyBoardApprovals can restrict approval notifications to request_board_approval approvals so internal CEO approvals stay inside Paperclip.

Install

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"}'

Troubleshooting: confirm your Paperclip host

Before filing a bug, confirm which Paperclip host this plugin is actually talking to. Run paperclipai plugin target (#8575) — it prints the resolved API URL plus the server's status, version, deploymentMode, and deploymentExposure before anything is installed. A server version older than this plugin expects is the most common cause of activation failures and secret-resolution errors (e.g. telegramBotTokenRef not resolving) that look like plugin bugs but aren't. If the URL or version is wrong, point Paperclip at the right host — or update the server — before opening an issue.

Setup

1. Open Telegram and chat with @BotFather

2. Run /newbot and follow the prompts to create a bot

3. Save the bot token

4. Send a message to your bot, then run curl "https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates" and find the chat.id field

5. In Paperclip, create a company secret holding your bot token, by either:

   • UI: Open any agent's Configuration → Environment variables, enter a name (e.g. telegram-bot-token) and the bot token as the value, then click Create / Seal. The secret is created at the company level (not bound to that agent — despite the agent-context UI) and the returned UUID can be used from any plugin in the company.
   • REST API: POST /api/companies/{companyId}/secrets with body {"name": "telegram-bot-token", "value": "<your-bot-token>", "provider": "local_encrypted"}. The response contains the secret's UUID.

   Copy the resulting secret UUID — you'll paste it into telegramBotTokenRef in the next step.

6. Configure the plugin with the secret UUID in telegramBotTokenRef and your chat ID in defaultChatId

7. If your Paperclip deployment requires authenticated board mutations, open the plugin settings page from a company context and complete Board Access Connection. This stores a Paperclip board API token as a company secret and lets Telegram approval actions authenticate without pasting raw tokens into the plugin config.

Configuration

Inbound security allowlists

Telegram does not provide a BotFather setting to disable direct messages while still allowing group use. To safely enable enableCommands or enableInbound, configure one or both allowlists:

• allowedTelegramUserIds: who may interact with the bot
• allowedTelegramChatIds: where interactions are accepted

If both allowlists are configured, both must match. For example, a user must be on the user allowlist and the message must come from an allowed DM or group chat.

The allowlists apply to:

• bot commands
• inbound replies routed back to Paperclip
• media intake
• inline button callbacks

Leave an allowlist empty only if that dimension should be unrestricted. After changing allowlists, save the plugin settings and restart the plugin if the new values are not picked up immediately.

Board access for approval actions

Approval buttons and /approve <approval-id> call Paperclip approval APIs. Authenticated Paperclip deployments may require a board API token for those mutations.

Use Board Access Connection on the plugin settings page to connect board access:

1. Open the Telegram plugin settings page inside a company.
2. Click Connect board access.
3. Approve the Paperclip board-access request in the opened window.

The plugin stores the resulting board API token as a Paperclip company secret and keeps only the secret reference in plugin state. The advanced paperclipBoardApiTokenRef config field is still supported for manual setups.

Agent tools

Comparison with PR #407

Migration

v0.2.1

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

1. Create a company secret holding your bot token using one of the paths in the Setup section above (UI or REST API).
2. Copy the returned secret UUID.
3. Open Plugin Settings for Telegram Bot and paste the UUID into "Telegram Bot Token".
4. Save and restart the plugin.

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

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build

~80 tests covering notifications, approvals, escalation, session registry, media pipeline, custom commands, proactive suggestions, MarkdownV2 formatting, and bot commands.

Contributing

Issues and PRs welcome at github.com/mvanhorn/paperclip-plugin-telegram.

Auto-publishes to npm on push to main via OIDC trusted publishing.

Credits

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

License

MIT