Files

Koshkoshinsk 2017589683 feat(telegram): self-contained pairing for chat ownership verification

BotFather issues bot tokens with no user binding, so anyone who guesses the
bot's username can DM it and get registered as a channel. Pairing closes that
gap: setup issues a one-time 4-digit code, the operator echoes it back from
the chat they want to register, and the inbound interceptor binds
admin_user_id before the message reaches the router.

- src/channels/telegram-pairing.ts: JSON-backed store with createPairing,
  tryConsume, getStatus, waitForPairing (fs.watch + poll fallback)
- src/channels/telegram.ts: wraps bridge.setup with an onInbound interceptor
  that consumes pairing codes and upserts messaging_groups
- setup/pair-telegram.ts: CLI step issues a code and waits up to 5 min for
  the operator to echo it back, emitting PLATFORM_ID/IS_GROUP/ADMIN_USER_ID
- Skill docs: /setup reorders mounts -> service -> wire (pairing needs a
  live polling adapter); /manage-channels and /add-telegram-v2 use pairing
  instead of asking the user to discover chat IDs

All other channels still bind admin via install-time identity (OAuth/QR/token);
pairing is Telegram-only. The bridge, router, and other adapters are untouched.

2026-04-13 12:27:02 +00:00

2.5 KiB

Raw Blame History

name, description

name	description
add-telegram-v2	Add Telegram channel integration to NanoClaw v2 via Chat SDK.

Add Telegram Channel

Adds Telegram bot support to NanoClaw v2 using the Chat SDK bridge.

Pre-flight

Check if src/channels/telegram.ts exists and the import is uncommented in src/channels/index.ts. If both are in place, skip to Credentials.

Install

Install the adapter package

npm install @chat-adapter/telegram

Enable the channel

Uncomment the Telegram import in src/channels/index.ts:

import './telegram.js';

Build

npm run build

Credentials

Create Telegram Bot

Open Telegram and search for @BotFather
Send /newbot and follow the prompts:
- Bot name: Something friendly (e.g., "NanoClaw Assistant")
- Bot username: Must end with "bot" (e.g., "nanoclaw_bot")
Copy the bot token (looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

Important for group chats: By default, Telegram bots only see @mentions and commands in groups. To let the bot see all messages:

Open @BotFather > /mybots > select your bot
Bot Settings > Group Privacy > Turn off

Configure environment

Add to .env:

TELEGRAM_BOT_TOKEN=your-bot-token

Sync to container: mkdir -p data/env && cp .env data/env/env

Next Steps

If you're in the middle of /setup, return to the setup flow now.

Otherwise, run /manage-channels to wire this channel to an agent group.

Channel Info

type: telegram
terminology: Telegram calls them "groups" and "chats." A "group" has multiple members; a "chat" is a 1:1 conversation with the bot.
how-to-find-id: Do NOT ask the user for a chat ID. Telegram registration uses pairing — run npx tsx setup/index.ts --step pair-telegram -- --intent <main|wire-to:folder|new-agent:folder>, show the user the 4-digit CODE from the PAIR_TELEGRAM_ISSUED block, and tell them to send @<botname> CODE from the chat they want to register (DM the bot for main, post in the group otherwise). The step waits up to 5 minutes and emits a PAIR_TELEGRAM block with PLATFORM_ID, IS_GROUP, and ADMIN_USER_ID once the user echoes the code. The service must be running for this to work (the polling adapter is what observes the code).
supports-threads: no
typical-use: Interactive chat — direct messages or small groups
default-isolation: Same agent group if you're the only participant across multiple chats. Separate agent group if different people are in different groups.

2.5 KiB Raw Blame History