Telegram Swarm

How it works

The /add-telegram-swarm skill adds Agent Teams (swarm) support to an existing Telegram channel. When your agent creates a team to tackle a complex task, each subagent appears as a different bot in the Telegram group — so you can visually distinguish who’s speaking.

The architecture uses a pool of send-only bots alongside your main Telegram bot. The main bot handles receiving messages and sending lead agent responses (this is already set up by /add-telegram). Pool bots are lightweight — they use Grammy’s Api class with no polling, just the ability to send messages.

When a subagent calls send_message with a sender parameter (like “Researcher” or “Code Reviewer”), the host assigns a pool bot to that sender name and renames the bot to match. The mapping is stable within a group — the same sender name always uses the same bot for the duration of the session, so the Telegram group shows a consistent identity for each team member.

Setup

Before running the skill, you need to create the pool bots:

1. Open Telegram and find @BotFather
2. Send /newbot for each bot (3-5 is typical). Give them placeholder names and usernames like myproject_swarm_1_bot
3. Copy all the tokens
4. For each bot, go to Bot Settings > Group Privacy > Turn off in BotFather. This lets pool bots send messages in groups.
5. Add all pool bots to your Telegram group(s)

The skill stores the tokens as a comma-separated list in the TELEGRAM_BOT_POOL environment variable.

What it looks like

When a team is active, your Telegram group shows messages from multiple bots. For example, if you ask NanoClaw to “assemble a team of a researcher and a coder”:

• NanoClaw (main bot): “I’ll create a team with a Researcher and a Coder.”
• Researcher (pool bot #1): “Starting web research on the topic…”
• Coder (pool bot #2): “Setting up the project structure.”
• Researcher (pool bot #1): “Found 3 relevant papers. Sharing with the team.”

Each bot has its own name and avatar position in the chat, making multi-agent conversations easy to follow.

Architecture

• Pool bots use Grammy’s Api class — lightweight instances that can send messages but don’t poll for incoming ones.
• Bot names are set via Telegram’s setMyName API. A 2-second delay after renaming allows Telegram to propagate the name change before the first message is sent.
• Sender-to-bot mapping is keyed as {groupFolder}:{senderName}, so different groups can independently assign bots.
• If all pool bots are assigned and a new sender appears, assignment wraps around (round-robin). The bot gets renamed to the new sender.
• Mapping resets on service restart — pool bots get reassigned fresh each time.

Tips

• 3-5 pool bots is enough for most use cases. Teams rarely have more than 5 active subagents, and round-robin handles overflow gracefully.
• Telegram caches bot names on the client side. After a pool bot is renamed, users may need to scroll or restart Telegram to see the updated name immediately.
• Pool bots are send-only. They don’t receive messages or respond to commands. All incoming messages go through the main bot.
• If a pool bot isn’t sending messages, verify its token with a getMe call and confirm it’s been added to the group with Group Privacy disabled.
• The skill modifies the send_message MCP tool to accept an optional sender parameter. This also requires rebuilding the container image.