add-telegram

# Add Telegram Channel This skill adds Telegram support to NanoClaw, then walks through interactive setup. ## Phase 1: Pre-flight ### Check if already applied Check if `src/channels/telegram.ts` exists. If it does, skip to Phase 3 (Setup). The code changes are already in place. ### Ask the user Use `AskUserQuestion` to collect configuration: AskUserQuestion: Do you have a Telegram bot token, or do you need to create one? If they have one, collect it now. If not, we'll create one in Phase 3. ## Phase 2: Apply Code Changes ### Ensure channel remote ```bash git remote -v ``` If `telegram` is missing, add it: ```bash git remote add telegram https://github.com/qwibitai/nanoclaw-telegram.git ``` ### Merge the skill branch ```bash git fetch telegram main git merge telegram/main || { git checkout --theirs package-lock.json git add package-lock.json git merge --continue } ``` This merges in: - `src/channels/telegram.ts` (TelegramChannel class with self-registration via `registerChannel`) - `src/channels/telegram.test.ts` (unit tests with grammy mock) - `import './telegram.js'` appended to the channel barrel file `src/channels/index.ts` - `grammy` npm dependency in `package.json` - `TELEGRAM_BOT_TOKEN` in `.env.example` If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides. ### Validate code changes ```bash npm install npm run build npx vitest run src/channels/telegram.test.ts ``` All tests must pass (including the new Telegram tests) and build must be clean before proceeding. ## Phase 3: Setup ### Create Telegram Bot (if needed) If the user doesn't have a bot token, tell them: > I need you to create a Telegram bot: > > 1. Open Telegram and search for `@BotFather` > 2. Send `/newbot` and follow prompts: > - Bot name: Something friendly (e.g., "Andy Assistant") > - Bot username: Must end with "bot" (e.g., "andy_ai_bot") > 3. Copy the bot token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`) Wait for the user to provide the token. ### Configure environment Add to `.env`: ```bash TELEGRAM_BOT_TOKEN=<their-token> ``` Channels auto-enable when their credentials are present — no extra configuration needed. Sync to container environment: ```bash mkdir -p data/env && cp .env data/env/env ``` The container reads environment from `data/env/env`, not `.env` directly. ### Disable Group Privacy (for group chats) Tell the user: > **Important for group chats**: By default, Telegram bots only see @mentions and commands in groups. To let the bot see all messages: > > 1. Open Telegram and search for `@BotFather` > 2. Send `/mybots` and select your bot > 3. Go to **Bot Settings** > **Group Privacy** > **Turn off** > > This is optional if you only want trigger-based responses via @mentioning the bot. ### Build and restart ```bash npm run build launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS # Linux: systemctl --user restart nanoclaw ``` ## Phase 4: Registration ### Get Chat ID Tell the user: > 1. Open your bot in Telegram (search for its username) > 2. Send `/chatid` — it will reply with the chat ID > 3. For groups: add the bot to the group first, then send `/chatid` in the group Wait for the user to provide the chat ID (format: `tg:123456789` or `tg:-1001234567890`). ### Register the chat The chat ID, name, and folder name are needed. Use `npx tsx setup/index.ts --step register` with the appropriate flags. For a main chat (responds to all messages): ```bash npx tsx setup/index.ts --step register -- --jid "tg:<chat-id>" --name "<chat-name>" --folder "telegram_main" --trigger "@${ASSISTANT_NAME}" --channel telegram --no-trigger-required --is-main ``` For additional chats (trigger-only): ```bash npx tsx setup/index.ts --step register -- --jid "tg:<chat-id>" --name "<chat-name>" --folder "telegram_<group-name>" --trigger "@${ASSISTANT_NAME}" --channel telegram ``` ## Phase 5: Verify ### Test the connection Tell the user: > Send a message to your registered Telegram chat: > - For main chat: Any message works > - For non-main: `@Andy hello` or @mention the bot > > The bot should respond within a few seconds. ### Check logs if needed ```bash tail -f logs/nanoclaw.log ``` ## Troubleshooting ### Bot not responding Check: 1. `TELEGRAM_BOT_TOKEN` is set in `.env` AND synced to `data/env/env` 2. Chat is registered in SQLite (check with: `sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE 'tg:%'"`) 3. For non-main chats: message includes trigger pattern 4. Service is running: `launchctl list | grep nanoclaw` (macOS) or `systemctl --user status nanoclaw` (Linux) ### Bot only responds to @mentions in groups Group Privacy is enabled (default). Fix: 1. `@BotFather` > `/mybots` > select bot > **Bot Settings** > **Group Privacy** > **Turn off** 2. Remove and re-add the bot to the group (required for the change to take effect) ### Getting chat ID If `/chatid` doesn't work: - Verify token: `curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe"` - Check bot is started: `tail -f logs/nanoclaw.log` ## After Setup If running `npm run dev` while the service is active: ```bash # macOS: launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist npm run dev # When done testing: launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist # Linux: # systemctl --user stop nanoclaw # npm run dev # systemctl --user start nanoclaw ``` ## Agent Swarms (Teams) After completing the Telegram setup, use `AskUserQuestion`: AskUserQuestion: Would you like to add Agent Swarm support? Without it, Agent Teams still work — they just operate behind the scenes. With Swarm support, each subagent appears as a different bot in the Telegram group so you can see who's saying what and have interactive team sessions. If they say yes, invoke the `/add-telegram-swarm` skill. ## Removal To remove Telegram integration: 1. Delete `src/channels/telegram.ts` and `src/channels/telegram.test.ts` 2. Remove `import './telegram.js'` from `src/channels/index.ts` 3. Remove `TELEGRAM_BOT_TOKEN` from `.env` 4. Remove Telegram registrations from SQLite: `sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE 'tg:%'"` 5. Uninstall: `npm uninstall grammy` 6. Rebuild: `npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `npm run build && systemctl --user restart nanoclaw` (Linux)