add-telegram

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

Add Telegram Channel

Adds Telegram bot support via the Chat SDK bridge.

Install

Telegram is the primary FamilyClaw channel and ships in trunk — the adapter (src/channels/telegram.ts + telegram-pairing.ts + telegram-markdown-sanitize.ts), the pair-telegram setup step, the channel flow, and the @chat-adapter/telegram dependency are all already present. There is nothing to fetch or copy.

Verify (idempotent)

These should all already be true on a fresh FamilyClaw checkout:

• src/channels/telegram.ts, telegram-pairing.ts, telegram-markdown-sanitize.ts exist
• src/channels/index.ts contains import './telegram.js';
• setup/pair-telegram.ts exists and setup/index.ts's STEPS map contains 'pair-telegram':
• @chat-adapter/telegram is listed in package.json dependencies

If any are missing (e.g. a partial checkout), run pnpm install && pnpm run build and re-check. Then continue to Credentials.

Credentials

Create Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts:
   • Bot name: Something friendly (e.g., "FamilyClaw Assistant")
   • Bot username: Must end with "bot" (e.g., "familyclaw_bot")
3. 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:

1. Open @BotFather > /mybots > select your bot
2. 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 pnpm exec 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 (follow the REMINDER_TO_ASSISTANT line in that block), and tell them to send just the 4 digits as a message from the chat they want to register (DM the bot for main, post in the group otherwise). In groups with Group Privacy ON, prefix with the bot handle: @<botname> CODE. Wrong guesses invalidate the code — if a PAIR_TELEGRAM_ATTEMPT block arrives with a mismatched RECEIVED_CODE, a PAIR_TELEGRAM_NEW_CODE block will follow automatically (up to 5 regenerations); show the new code. On PAIR_TELEGRAM STATUS=failed ERROR=max-regenerations-exceeded, ask the user if they want to try again and re-invoke the step — each invocation starts a fresh 5-attempt batch. Success emits PAIR_TELEGRAM STATUS=success with PLATFORM_ID, IS_GROUP, and ADMIN_USER_ID. 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.