Telegram integration

This page is pending a v2 rewrite. The /add-telegram skill flow still works, but some mechanics described below reflect v1 architecture — in v2, channel adapters live on a single channels branch. See Integrations overview for current context.

Add Telegram as a messaging channel for NanoClaw. Telegram can run alongside existing channels or replace them entirely.

Overview

The Telegram integration uses the grammy library to connect to Telegram’s Bot API. It supports all core NanoClaw features including group chats, isolated contexts, scheduled tasks, and typing indicators.

Features

Full channel support - Direct messages, group chats, and channels
Forum topics - Replies land in the correct topic thread in supergroups
Bot commands - Built-in /chatid command for registration
Typing indicators - Shows when the assistant is working
Concurrent chats - Handle multiple conversations simultaneously
Flexible deployment - Run alongside existing channels or as the only channel

Adding Telegram

Use the /add-telegram skill to add Telegram support:

Run the skill

claude
/add-telegram

Choose deployment mode

Replace existing channels - Telegram becomes the only channel
Alongside - Add Telegram alongside existing channels

Apply code changes

The skill merges the skill/telegram branch which adds:

src/channels/telegram.ts (TelegramChannel implementation)
src/channels/telegram.test.ts (46 unit tests)
Multi-channel support in src/index.ts
Telegram config in src/config.ts
The grammy NPM package

Create Telegram bot

If you don’t have a bot token yet, create one through @BotFather

Configure environment

Add bot token to .env and sync to container

Use the /chatid command to get chat IDs and register them

Creating a Telegram bot

If you don’t already have a Telegram bot:

Open Telegram

Search for @BotFather and start a conversation

Create the bot

Send /newbot and follow the prompts:

Bot name: Something friendly (e.g., “Andy Assistant”)
Bot username: Must end with “bot” (e.g., “andy_ai_bot”)

Save the token

Copy the bot token. It looks like:

123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Configuration

Environment variables

Add to .env:

TELEGRAM_BOT_TOKEN=<your-bot-token>

If you chose to replace existing channels:

TELEGRAM_ONLY=true

Sync to container

The container reads environment from data/env/env:

mkdir -p data/env && cp .env data/env/env

Group privacy settings

By default, Telegram bots only see messages that @mention them or start with / in group chats. To let the bot see all messages in groups:

Open @BotFather

Search for @BotFather in Telegram

Select your bot

Send /mybots and select your bot from the list

Disable group privacy

Go to Bot Settings → Group Privacy → Turn off

This is optional. If you only want trigger-based responses (via @mentions), leave group privacy enabled.

Build and restart

After configuration:

pnpm run build
launchctl list | grep nanoclaw
launchctl kickstart -k gui/$(id -u)/<label>

Registering chats

Get chat ID

Start conversation

Open your bot in Telegram (search for its username)

Get the chat ID

Send /chatid to the bot. It will reply with the chat ID:

Your chat ID: tg:123456789

For group chats

Add the bot to the group
Send /chatid in the group
The bot will reply with the group’s chat ID (format: tg:-1001234567890)

Register the chat

For your main chat (responds to all messages):

registerGroup("tg:<chat-id>", {
  name: "Main",
  folder: "main",
  trigger: `@${ASSISTANT_NAME}`,
  added_at: new Date().toISOString(),
  requiresTrigger: false,
});

For additional chats (trigger-only):

registerGroup("tg:<chat-id>", {
  name: "Team Chat",
  folder: "team-chat",
  trigger: `@${ASSISTANT_NAME}`,
  added_at: new Date().toISOString(),
  requiresTrigger: true,
});

Set requiresTrigger: true for group chats so the assistant only responds when explicitly mentioned.

Testing the connection

Send a message to your registered Telegram chat:

For main chat: Any message works
For non-main chats: @Andy hello or @mention the bot

The bot should respond within a few seconds.

Check logs

tail -f logs/nanoclaw.log

Look for:

Connected to Telegram
Received message from tg:123456789
Agent response queued

JID format

Telegram chats use the tg: prefix:

Individual chat: tg:123456789
Group chat: tg:-1001234567890
Channel: tg:-1001234567890

Forum topics (supergroups)

Telegram supergroups can enable Topics to organize conversations into threads. The Telegram integration automatically tracks message_thread_id from incoming messages and routes replies to the correct topic.

How it works

When a user messages the bot from a specific topic, the bot extracts the message_thread_id
Replies and typing indicators are sent back to the same topic thread
Non-forum groups (without topics enabled) work as before — no configuration needed

Forum topics support requires no additional setup. The bot detects and tracks thread IDs automatically.

Enabling topics in a group

Open your Telegram supergroup settings
Go to Topics and enable them
The bot will automatically reply within the correct topic

If the bot was already added to the group before topics were enabled, no changes are needed — it picks up thread IDs from new incoming messages.

Implementation details

The Telegram channel implements the Channel interface. Incoming messages include the thread_id when sent from a forum topic, and outgoing messages route to the correct thread:

export class TelegramChannel implements Channel {
  name = 'telegram';
  
  async connect(): Promise<void> {
    this.bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
    
    // Handle text messages
    this.bot.on('message:text', async (ctx) => {
      const chatId = `tg:${ctx.chat.id}`;
      const threadId = ctx.message.message_thread_id;
      this.opts.onMessage(chatId, {
        id: ctx.message.message_id.toString(),
        chat_jid: chatId,
        sender: `${ctx.from.id}`,
        sender_name: ctx.from.first_name,
        content: ctx.message.text,
        timestamp: new Date(ctx.message.date * 1000).toISOString(),
        is_from_me: ctx.from.is_bot,
        is_bot_message: ctx.from.id === this.bot.botInfo?.id,
        thread_id: threadId ? threadId.toString() : undefined,
      });
    });
    
    await this.bot.start();
  }
  
  async sendMessage(jid: string, text: string, threadId?: string): Promise<void> {
    const chatId = jid.replace('tg:', '');
    const options = threadId
      ? { message_thread_id: parseInt(threadId, 10) }
      : {};
    await this.bot.api.sendMessage(chatId, text, options);
  }
}

Troubleshooting

Bot not responding

Check these common issues:

Token not configured

Verify TELEGRAM_BOT_TOKEN is set in .env and synced to data/env/env:

grep TELEGRAM_BOT_TOKEN .env
grep TELEGRAM_BOT_TOKEN data/env/env

Chat not registered

Check if the chat is in the database:

sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE 'tg:%'"

Service not running

Check if NanoClaw is running:

# macOS
launchctl list | grep nanoclaw

# Linux
systemctl --user status nanoclaw

Trigger pattern not matched

For non-main chats with requiresTrigger: true, messages must include the trigger pattern (e.g., @Andy).

Bot replies in General instead of the correct topic

If your supergroup has topics enabled but the bot always replies in the General thread:

Make sure you’re running the latest version of the Telegram skill — topic support was added in the message_thread_id fix

Re-merge the skill branch to pick up the update:

git fetch telegram main
git merge telegram/main

Rebuild and restart NanoClaw

Bot only responds to @mentions in groups

This is the default Telegram behavior. To change:

Open @BotFather
Send /mybots and select your bot
Bot Settings → Group Privacy → Turn off
Remove and re-add the bot to the group (required for change to take effect)

Getting chat ID fails

If /chatid doesn’t work:

Verify the bot token:

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe"

Check that NanoClaw is running:
```
tail -f logs/nanoclaw.log
```
Make sure the bot is started (it should connect on launch)

Agent swarms (teams)

The /add-telegram-swarm skill extends the Telegram integration with specialized agent swarm support. Each subagent appears as a different Telegram bot in the group, making it clear which agent is speaking.

How it works

Each swarm agent gets its own Telegram bot token and identity
When the orchestrator delegates to a subagent, that agent’s responses come from its own bot
Users can see which agent is working on what, and interact with specific agents directly
The orchestrator coordinates the team and routes tasks

Installation

The swarm skill depends on the base Telegram integration. If you already have /add-telegram applied:

# On your nanoclaw-telegram fork
git fetch telegram skill/telegram-swarm
git merge telegram/skill/telegram-swarm

Or via Claude Code:

/add-telegram-swarm

Configuration

Each swarm agent needs its own bot token. Create additional bots via @BotFather and add their tokens to .env:

TELEGRAM_BOT_TOKEN=<orchestrator-bot-token>
TELEGRAM_SWARM_BOT_TOKENS=<agent1-token>,<agent2-token>,<agent3-token>

The swarm skill has a 14KB SKILL.md with detailed setup instructions. Running /add-telegram-swarm in Claude Code walks you through the full configuration interactively.

See Agent swarms for general swarm concepts.

Removing Telegram

Since Telegram was added via a git merge, you remove it by reverting the merge commit:

Find the merge commit

git log --merges --oneline | grep telegram

Look for a commit like abc1234 Merge remote-tracking branch 'upstream/skill/telegram'.

Revert the merge

git revert -m 1 <merge-commit>

This creates a new commit that undoes all of Telegram’s code changes.

Remove registrations

sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE 'tg:%'"

Rebuild and restart

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

If you later want to re-apply Telegram after reverting, you must revert the revert first — git treats reverted changes as “already applied and undone”. Claude handles this automatically when you run /add-telegram again.

Next steps

Add Discord

Add Discord support to your installation

Add Slack

Add Slack support to your installation

Skills system

Learn more about how skills work

Get Started

Core Concepts

Features

Integrations

Advanced

Changelog

Telegram integration

Overview

Features

Adding Telegram

Creating a Telegram bot

Configuration

Environment variables

Sync to container

Group privacy settings

Build and restart

Registering chats

Get chat ID

Register the chat

Testing the connection

Check logs

JID format

Forum topics (supergroups)

How it works

Enabling topics in a group

Implementation details

Troubleshooting

Bot not responding

Bot replies in General instead of the correct topic

Bot only responds to @mentions in groups

Getting chat ID fails

Agent swarms (teams)

How it works

Installation

Configuration

Removing Telegram

Next steps

Add Discord

Add Slack

Skills system

Get Started

Core Concepts

Features

Integrations

Advanced

Changelog

Documentation Index

​Overview

​Features

​Adding Telegram

​Creating a Telegram bot

​Configuration

​Environment variables

​Sync to container

​Group privacy settings

​Build and restart

​Registering chats

​Get chat ID

​Register the chat

​Testing the connection

​Check logs

​JID format

​Forum topics (supergroups)

​How it works

​Enabling topics in a group

​Implementation details

​Troubleshooting

​Bot not responding

​Bot replies in General instead of the correct topic

​Bot only responds to @mentions in groups

​Getting chat ID fails

​Agent swarms (teams)

​How it works

​Installation

​Configuration

​Removing Telegram

​Next steps

Add Discord

Add Slack

Skills system

Overview

Features

Adding Telegram

Creating a Telegram bot

Configuration

Environment variables

Sync to container

Group privacy settings

Build and restart

Registering chats

Get chat ID

Register the chat

Testing the connection

Check logs

JID format

Forum topics (supergroups)

How it works

Enabling topics in a group

Implementation details

Troubleshooting

Bot not responding

Bot replies in General instead of the correct topic

Bot only responds to @mentions in groups

Getting chat ID fails

Agent swarms (teams)

How it works

Installation

Configuration

Removing Telegram

Next steps