Skip to main content
The Add Telegram skill installs Telegram support in NanoClaw. It handles code installation via the skills engine, bot creation, authentication, and chat registration.

​
What It Does

The Add Telegram skill:
  • Installs Telegram channel code and dependencies
  • Guides through bot creation with @BotFather
  • Configures bot token authentication
  • Registers chats (DM or groups)
  • Optionally enables Agent Swarm support for team sessions

​
Prerequisites

  • NanoClaw base installation complete
  • Telegram account
  • Access to @BotFather on Telegram

​
How to Apply

1

Invoke the skill

Run /add-telegram in your NanoClaw context.
2

Create Telegram bot

If you don’t have a bot token:
  1. Open Telegram and search for @BotFather
  2. Send /newbot and follow prompts
  3. Bot name: Something friendly (e.g., “Andy Assistant”)
  4. Bot username: Must end with “bot” (e.g., “andy_ai_bot”)
  5. Copy the bot token (123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
3

Apply code changes

The skill runs npx tsx scripts/apply-skill.ts .claude/skills/add-telegram which:
  • Adds src/channels/telegram.ts
  • Adds unit tests
  • Installs grammy dependency
  • Updates channel registry
4

Configure environment

The skill adds TELEGRAM_BOT_TOKEN to .env and syncs to container.
5

Get chat ID

  1. Open your bot in Telegram
  2. Send /chatid - it replies with the chat ID
  3. For groups: add the bot first, then send /chatid in the group
6

Register chat

The skill registers the chat with:
  • Chat ID (format: tg:123456789)
  • Chat name
  • Trigger requirement (main vs. trigger-only)

​
What Changes

​
Files Created

  • src/channels/telegram.ts - Telegram channel implementation
  • src/channels/telegram.test.ts - Unit tests (46 tests)
  • groups/telegram_main/ - Main chat workspace (if registered as main)

​
Files Modified

  • package.json - Adds grammy dependency
  • src/channels/index.ts - Imports Telegram channel
  • .env - Adds TELEGRAM_BOT_TOKEN
  • data/env/env - Synced environment for container
  • .nanoclaw/state.yaml - Records skill application
  • store/messages.db - Adds registered chat entries

​
Dependencies Added

  • grammy - Telegram Bot API framework

​
Usage

​
Main Chat (No Trigger Required)

In your main chat, any message triggers the assistant: 
You: What's the weather?
Andy: [responds immediately]

​
Additional Chats (Trigger Required)

In other chats, use the trigger word or @mention: 
You: @Andy what's the weather?
Andy: [responds]

You: regular message
Andy: [no response]

​
Group Privacy Setting

For group chats where you want the bot to see all messages (not just @mentions):
  1. Open Telegram and search for @BotFather
  2. Send /mybots and select your bot
  3. Go to Bot Settings > Group Privacy > Turn off
  4. Remove and re-add the bot to the group
Telegram bots run alongside other channels. If you have WhatsApp configured, both channels work simultaneously. The agent auto-enables when TELEGRAM_BOT_TOKEN is present in .env.

​
Agent Swarms (Teams)

After Telegram setup, you can add Agent Swarm support. This makes each subagent appear as a different bot in group chats, so you can see team conversations. Without Swarm support, Agent Teams still work - they just operate behind the scenes. To enable: Run /add-telegram-swarm after completing Telegram setup.

​
Troubleshooting

​
Bot Not Responding

Check:
  1. TELEGRAM_BOT_TOKEN is set in .env AND synced to data/env/env
  2. Chat is registered: 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

​
Bot Only Responds to @Mentions in Groups

Group Privacy is enabled (default). To fix:
  1. @BotFather > /mybots > select bot > Bot Settings > Group Privacy > Turn off
  2. Remove and re-add the bot to the group

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us