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

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.claudeclaw

   (macOS) or

   npm run build && systemctl --user restart claudeclaw

   (Linux)