/add-telegram

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 ClaudeClaw, 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

git remote -v

If `telegram` is missing, add it:

git remote add telegram https://github.com/qwibitai/claudeclaw-telegram.git

Merge the skill branch

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

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`:

TELEGRAM_BOT_TOKEN=<their-token>

Channels auto-enable when their credentials are present — no extra configuration needed.

Sync to container environment:

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.

> **Service name:** Derived from the directory name: `com.claudeclaw.<dirname>` (macOS) / `claudeclaw-<dirname>` (Linux). For example, if cwd is `my-assistant`, the service is `com.claudeclaw.my-assistant`. Determine the correct service name before running service commands below.

Build and restart

npm run build
launchctl kickstart -k gui/$(id -u)/com.claudeclaw  # macOS
# Linux: systemctl --user restart claudeclaw

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):

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):

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

tail -f logs/claudeclaw.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 claudeclaw` (macOS) or `systemctl --user status claudeclaw` (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/claudeclaw.log`

After Setup

If running `npm run dev` while the service is active:

# macOS:
launchctl unload ~/Library/LaunchAgents/com.claudeclaw.plist
npm run dev
# When done testing:
launchctl load ~/Library/LaunchAgents/com.claudeclaw.plist
# Linux:
# systemctl --user stop claudeclaw
# npm run dev
# systemctl --user start claudeclaw