Finch Telegram Bot

Connect a Telegram Bot to Finch as a private, mobile-friendly inbox. Each paired Telegram private chat maps to one owner-scoped Finch Session, and replies are delivered back through the Telegram Bot API.

Release Status

Current release: 0.3.2

This release focuses on private Telegram chats and safely relays selected Finch interactions. Paired users can answer single-choice questions and allow or deny non-destructive permissions with short-lived inline buttons. On Finch 1.6.1 or later, Bot settings can dynamically switch all current and future Telegram Sessions between asking for permissions and automatically allowing non-destructive tool calls. The setting is hidden when the runtime API is unavailable, and destructive approval remains restricted to Finch Desktop.

Deliberate boundaries

This mini tool remains private-chat only. Group and supergroup routing, topic bindings, remote destructive approval, secret-form relay, model/Agent switching, and remote Session browsing are intentionally out of scope. A Telegram group administrator is never treated as a Finch administrator, and no Telegram response becomes a remembered Finch permission rule.

Features

• Native Bot Token setup backed only by ctx.secrets
• Token validation with getMe before it is saved
• Long polling with persisted offsets, bounded reconnect backoff, poison-update quarantine, cancellation, and conflict detection
• Explicit webhook takeover instead of silently deleting an existing webhook
• Short-lived, in-memory pairing codes with bounded guessing attempts and explicit unpairing
• A Finch Pet-style settings menu with cached instant opening, background Telegram status refresh, paired-user count, compact user list, profile details, and per-user unpair controls
• Bounded Telegram display names and usernames refreshed on pairing and later authorized messages
• One reusable Finch Session per paired chat, plus an idempotent /new command for a fresh Session
• Inbound Telegram photos and documents forwarded as bounded Finch Session attachments (up to 20 MB)
• Recoverable terminal reply delivery with duplicate suppression across Finch restarts
• Short-lived, user-bound inline buttons for single-choice questions and one-time non-destructive permission decisions
• Capability-gated permission mode setting on Finch 1.6.1+: dynamically updates current and future Telegram Sessions, and stays hidden on older runtimes
• Destructive permissions can be denied remotely but require Finch Desktop for approval; forms remain on the trusted desktop surface
• Proactive text sending, typing indicators, 4096-character-safe chunking, per-chat pacing, and bot-wide rate control
• A minimal Telegram command menu (/start, /help, /pair, /new, /status) registered in English and Chinese
• Safe Markdown-to-Telegram-HTML rendering with strict escaping and automatic plain-text fallback
• One Agent tool, telegram_bot_manage, with action-based configuration, status, pairing, sending, and Session management
• English defaults and zh-CN localization

Requirements

• Finch Desktop 1.6.0 or later
• A Telegram Bot Token created through @BotFather
• Finch must remain running to receive updates in long-polling mode

Setup

1. Open Telegram and create a bot with @BotFather using /newbot.
2. Install and enable this mini tool in Finch.
3. Open the mini tool settings menu and select Configure Bot Token.
4. Paste the token into the native password field. The value is validated and written directly to the operating system secure credential store.
5. Open Bot settings → Message transport to see the live Bot API state. If a webhook exists, review its endpoint and confirm migration only when Finch should take over the bot.
6. Select Pair new user. Finch shows a one-time code in a native dialog.
7. Open a private chat with the bot and send /pair CODE within ten minutes.
8. Send a normal Telegram message. Finch creates or reuses the chat's inbox Session and sends the final response back.

Useful Telegram commands:

• /start — show usage guidance
• /help — show the complete minimal command list
• /new — switch this chat to a fresh Finch Session
• /status — verify that the bridge is responding
• /pair CODE — authorize a private chat using the short-lived code shown in Finch

Agent tool

The mini tool exposes one tool: telegram_bot_manage.

| Action | Purpose | | --- | --- | | configure | Collect and validate the token in a native secure form | | status | Check bot identity, polling state, webhook state, and paired-chat count | | webhook | Inspect webhook state and confirm migration only when an endpoint exists | | start | Start long polling when no webhook is configured | | stop | Stop polling while retaining the token and mappings | | pair | Show a short-lived pairing code in a native dialog | | send | Send text to an already paired private chat | | list_chats | List paired chat IDs and active Session IDs | | unpair | Revoke one chat and remove its active routing mappings | | new_session | Activate a fresh Finch Session for a paired chat | | clear_token | Delete the secure token and clear Telegram mappings |

Why long polling

Telegram offers two mutually exclusive update transports: getUpdates long polling and webhooks. A local desktop mini tool normally has no stable public HTTPS endpoint, certificate, or always-reachable inbound port. Long polling therefore provides the safest zero-server setup and works behind NAT.

The bridge checks getWebhookInfo before polling and whenever the settings menu opens. Token setup never changes webhook configuration. Message transport displays either Finch long polling or the detected webhook host; migration is offered only when an endpoint exists, with the impact shown before explicit confirmation. HTTP 409 is treated as a terminal receiver conflict rather than retried forever.

See docs/ARCHITECTURE.md for the detailed design and source research.

Security and privacy

• The Bot Token is declared as telegram.botToken and accessed only through ctx.secrets.
• The token is never stored in ctx.storage, JSON, logs, i18n files, or tool results.
• Pairing codes live only in memory, expire after ten minutes, and are shown only in Finch native UI.
• Invalid pairing attempts are limited per chat and the in-memory limiter is size-bounded.
• Only paired private chats are accepted. Group, supergroup, and channel messages are ignored; unpair revokes future routing immediately.
• Non-secret routing state—chat/user IDs, bounded display names and usernames, Session IDs, turn routes, and polling offset—is stored in the mini tool's private plaintext storage.
• Changing the Bot Token clears old chat mappings so authorization cannot cross bot identities.
• No telemetry or third-party relay service is used; network access is limited to Telegram's official Bot API.

Read SECURITY.md before enabling the bot for sensitive workflows.

Current scope

Version 0.3 focuses on secure private conversations plus bounded remote interaction relay. It accepts Telegram text, photos, and documents; attachment downloads and Finch Session payloads are capped at 20 MB. Outbound replies remain text-only, with safe Telegram HTML formatting and plain-text fallback. New Telegram Sessions run in interactive ask mode so waits can surface. A paired private-chat user may answer one single-choice question or allow/deny one non-destructive permission through a ten-minute, one-use inline button. Destructive approval, multi-question or multi-select prompts, and all forms remain in Finch Desktop. Existing background Sessions are replaced with an interactive Session on their next message.

Development

npm install
npm run check
npx @finchtoys/minitools doctor .

The project is a standalone npm-style Finch mini tool. It uses the published @finchtoys/minitool-api type contract through that package's documented finch module alias. Runtime code lives in src/, tests in tests/, maintenance scripts in scripts/, and compiled output in dist/. The package allowlist ships only runtime assets and documentation; source, tests, and local build configuration are excluded from the npm tarball.

License

MIT. Research sources and license attributions are recorded in THIRD_PARTY_NOTICES.md. No external Telegram framework is bundled at runtime.