d572bab5c6
Move skill definitions from the nanoclaw-skills marketplace plugin into .claude/skills/ so they're available as unprefixed slash commands (e.g. /add-whatsapp instead of /nanoclaw-skills:add-whatsapp). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
232 lines
6.4 KiB
Markdown
232 lines
6.4 KiB
Markdown
---
|
|
name: add-telegram
|
|
description: Add Telegram as a channel. Can replace WhatsApp entirely or run alongside it. Also configurable as a control-only channel (triggers actions) or passive channel (receives notifications only).
|
|
---
|
|
|
|
# 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
|
|
```
|
|
|
|
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
|
|
|
|
Use the IPC register flow or register directly. The chat ID, name, and folder name are needed.
|
|
|
|
For a main chat (responds to all messages):
|
|
|
|
```typescript
|
|
registerGroup("tg:<chat-id>", {
|
|
name: "<chat-name>",
|
|
folder: "telegram_main",
|
|
trigger: `@${ASSISTANT_NAME}`,
|
|
added_at: new Date().toISOString(),
|
|
requiresTrigger: false,
|
|
isMain: true,
|
|
});
|
|
```
|
|
|
|
For additional chats (trigger-only):
|
|
|
|
```typescript
|
|
registerGroup("tg:<chat-id>", {
|
|
name: "<chat-name>",
|
|
folder: "telegram_<group-name>",
|
|
trigger: `@${ASSISTANT_NAME}`,
|
|
added_at: new Date().toISOString(),
|
|
requiresTrigger: true,
|
|
});
|
|
```
|
|
|
|
## 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)
|