Download .claude/skills/add-telegram/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does add-telegram live?
The publisher keeps it at https://github.com/nanocoai/nanoclaw.
Which agents can use add-telegram?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.
Add Telegram channel integration via Chat SDK.
name: add-telegram
description: Add Telegram channel integration via Chat SDK.
Add Telegram Channel
Adds Telegram bot support via the Chat SDK bridge. NanoClaw doesn't ship
channels in trunk — this skill copies the Telegram adapter, its pairing helper,
and their tests in from the channels branch. The
pair-telegram setup step is maintained in trunk, so it is not copied here.
The mechanical steps under Apply carry nc: directive fences: an agent
reads the prose and applies them, and a parser can apply them deterministically
from the same document. Every directive is idempotent, so the whole skill is
safe to re-run; anything a parser can't apply falls back to the prose beside it.
Re-running with a bot already configured can add a second one instead of
re-pairing the first; see Add another bot under Credentials.
Apply
1. Copy the adapter, helpers, and tests
Fetch the channels branch and copy the Telegram adapter, its pairing helper
(with its test), and the focused adapter tests into place (overwrite — the
branch is canonical):
Append the self-registration import to the channel barrel (skipped if the line
is already present). This one line is the skill's only reach-in into core:
import './telegram.js';
3. Register the pairing setup step
Add the pair-telegram loader to the STEPS map in setup/index.ts, inside the
dormant marker region (skipped if already present — pair-telegram ships in core,
so this idempotent-skips on a normal install, but is expressed for a
clean-upstream rebuild). The pairing handshake below spawns this step:
Build first: it guards the typed createChatSdkBridge(...) core call and proves
the dependency is installed. Then run the focused tests.
pnpm run build
pnpm exec vitest run src/channels/telegram-registration.test.ts src/channels/telegram-connect-group.test.ts
telegram-registration.test.ts imports the real channel barrel and asserts the
registry contains telegram. It goes red if the import line is deleted or drifts,
if the barrel fails to evaluate, or if @chat-adapter/telegram isn't installed
(the import throws) — so it also covers the dependency from step 4. End-to-end
delivery against a real bot is verified manually once the service runs.
Credentials
An install that already holds TELEGRAM_BOT_TOKEN can add a second bot instead of
re-pairing the first. Check which case this is; the answer steers the rest of the
flow:
grep -qsE '^TELEGRAM_BOT_TOKEN=.+' .env && echo yes || echo no
On a first install there is no bot to add another to, so add_another is no and
the steps below create and configure the first bot. When a bot is already configured, ask the
user whether to keep using it (no: the stored token stays as it is and the flow
re-pairs that bot) or to add another one (yes: the first bot's steps are satisfied
by the stored token and change nothing; the new bot is handled under Add another
bot):
A Telegram bot is already configured (TELEGRAM_BOT_TOKEN in .env). Add another bot (yes), or keep using the existing one (no)?
Bot creation in Telegram is human and interactive — no parser can click through
BotFather. The adapter is installed and registered, but it can't receive a
message until the bot exists. On a first install, tell the user (a bot that is
already configured keeps its stored token below; a second one is created under
Add another bot):
Create the Telegram bot:
1. Open Telegram and message @BotFather — Telegram's official bot for creating bots.
2. Send /newbot and follow the prompts: a friendly name, then a username that must end in "bot".
3. Copy the bot token it gives you (looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11a).
4. Planning to use the bot in group chats? Send /mybots → your bot → Bot Settings → Group Privacy → Turn off, so the bot can see all messages and not just @mentions.
Collect the bot token and store it — the bridge reads it from .env (set-if-absent,
so a value you've already filled in is never overwritten) and syncs it to the
container:
Paste the bot token from BotFather (looks like `123456:ABC-DEF...`).
TELEGRAM_BOT_TOKEN={{bot_token}}
Confirm the token works and capture the bot's handle — getMe returns the bot
account and fails here if the token is bad. You'll use the handle to open the
right chat just before pairing:
Only when add_another is yes. The second bot is a named adapter instance: its
short name becomes the registry key telegram-<name> and, uppercased with dashes as
underscores, the token key suffix (gh-bot stores TELEGRAM_BOT_TOKEN_GH_BOT). A
name whose TELEGRAM_BOT_TOKEN_<NAME> key is already set is taken (storing under it
would overwrite that bot's token), so it is refused:
Short name for the new bot (lowercase letters, digits, dashes; e.g. `mega`). Pick one whose token key is not already set in .env.
To pair an already-configured named bot again instead (its token is stored and the
service restarted, but pairing failed or was cancelled), run
pnpm exec tsx setup/index.ts --step pair-telegram -- --intent main --instance telegram-<name>,
then /init-first-agent with --instance telegram-<name> if it was never wired.
The second bot is created with @BotFather exactly like the first. Tell the user:
Create the second Telegram bot: message @BotFather, send /newbot and follow the prompts (its own friendly name, then a username that must end in "bot"), and copy the token it gives you. It must be a different bot from the one already configured. Planning to use it in group chats? Send /mybots → that bot → Bot Settings → Group Privacy → Turn off.
Then confirm its token with getMe as above:
Paste the second bot's token from BotFather (looks like `123456:ABC-DEF...`). It must belong to a different bot than the one already configured.
A second token that resolves to the same bot as the first (its handle matches) is
refused here, before anything is written: it would only start a second poller on
that bot, which the adapter refuses at startup anyway.
[ "{{bot_username_2}}" != "{{bot_username}}" ]
Store the token under its suffixed key and list the name in TELEGRAM_INSTANCES,
merged with the names already there. Both writes go through the set-env step,
which updates an existing key and logs the key, never the value:
The registry key is how pairing and wiring address the new bot:
echo telegram-{{bot_name}}
Restart
Restart the service so it loads the Telegram adapter and the token you just
stored, and wait for its CLI socket. The adapter must be live and polling before
pairing — it's the thing that observes the code you send:
bash setup/lib/restart.sh
Pair your chat
Telegram tokens carry no user binding, so the agent proves you own the chat with
a one-time pairing handshake: it issues a 6-digit code, you send those exact 6
digits to the bot from the chat you want to register, and the live adapter
matches them. Open the bot first so you're on the right screen when the code
appears. Tell the user:
Open @{{bot_username}} (https://telegram.me/{{bot_username}}) in Telegram now and keep it on screen — a 6-digit pairing code is about to appear in this terminal. When it does, send just those 6 digits to the bot as a message (in a group chat with Group Privacy on, prefix them with @{{bot_username}}). A wrong guess is rejected and a fresh code is issued automatically.
Run the pairing handshake. It prints the code, streams "waiting…" and wrong-code
feedback while it watches for your message, and resolves your chat address
telegram:<chatId> plus your Telegram user id once the code matches:
pnpm exec tsx setup/index.ts --step pair-telegram -- --intent main
A second bot pairs through its own instance key: the code is bound to
telegram-<name>, the first bot ignores it, and the paired chat gets its own
messaging-group row for that instance (a bot cannot message a user who never opened
it, so the chat id known from the first bot is not reused). Tell the user:
Open @{{bot_username_2}} (https://telegram.me/{{bot_username_2}}) in Telegram now and keep it on screen: a pairing code is about to appear in this terminal. Send just those digits to this new bot, not to the first one. A wrong guess is rejected and a fresh code is issued automatically.
owner_handle (your Telegram user id) and platform_id (telegram:<chatId>)
are what the owner-wiring step needs. The greeting goes out over the same chat as
soon as pairing completes. For a second bot, instance (telegram-<name>) comes
along too: pass it as --instance to scripts/init-first-agent.ts so the DM row,
the wiring and the welcome all target that bot (see /init-first-agent).
Next Steps
If you're in the middle of /setup, return to the setup flow now. Otherwise wire
this channel with /init-first-agent (or /manage-channels).
Connect a group
After the first DM is paired, an owner or global admin can send /connect_group in
their bot DM. The bot replies with Telegram's native group picker. Choosing a
group adds the bot and posts an addressed start command there; NanoClaw then
sends its existing channel-registration approval card to an eligible
owner/admin DM. Nothing is wired until that card is approved.
The picker link is navigation, not authorization: it carries no secret and
creates no role, member, messaging-group, or wiring row. The existing approval
flow remains the authority. If the picker is unavailable, add the bot to the
group manually and post /start@{{bot_username}} connect there to reach the
same approval card.
If the negative Telegram chat ID is already known, the fully manual ncl
equivalent is:
wirings create applies Telegram's group defaults and creates the companion
destination row. Prefer /connect_group when the ID is unknown; it discovers
the group and keeps the approval card in the loop.
Channel Info
type: telegram
terminology: Telegram calls them "groups" and "chats." A "group" has multiple members; a "chat" is a 1:1 conversation with the bot.
platform-id-format: telegram:{chatId} (e.g. telegram:123456789 for a DM, telegram:-1001234567890 for a group — negative chat IDs are groups/channels).
how-to-find-id: Do NOT ask the user for a chat ID. Pair the first DM with pnpm exec tsx setup/index.ts --step pair-telegram -- --intent main. For another group, have an owner/global admin send /connect_group in that paired DM, choose the group, and approve the resulting channel-registration card. The service must be running — the polling adapter observes both flows.
instances: TELEGRAM_BOT_TOKEN is the default instance telegram; TELEGRAM_INSTANCES=<name>,... plus TELEGRAM_BOT_TOKEN_<NAME> adds telegram-<name> (reference: .claude/skills/telegram-multi-instance/SKILL.md on the channels branch).
supports-threads: no
typical-use: Interactive chat — direct messages or small groups
default-isolation: Same agent group if you're the only participant across multiple chats. Separate agent group if different people are in different groups.
Troubleshooting
The bot token paste is rejected. A BotFather token is <numeric bot id>:<35+ character secret> — e.g. 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11a. Pasting only the part after the colon, or the bot's @username, won't pass. Recover the full token any time by sending /token to @BotFather.
getMe fails. The token was revoked (a /revoke or a fresh /token invalidates the old value) or picked up whitespace in the paste. Get the current token from BotFather and re-paste it.
Pairing never completes. The live adapter is what observes the code, so the service must be running — the restart step comes before pairing for exactly this reason. Send just the 6 digits from the exact chat you want registered; in a group with Group Privacy on, prefix them with @<botname>. Wrong guesses are fine (a fresh code is issued, up to 5 times), but a dead adapter waits forever.
The bot ignores group messages. Group Privacy is on, so the bot only sees addressed commands and replies, not ordinary @bot text. BotFather → /mybots → your bot → Bot Settings → Group Privacy → Turn off — then remove and re-add the bot to the group so the change takes effect.
/connect_group is denied. The Telegram sender is not a NanoClaw owner or global admin. The command never grants privileges; inspect them with ncl roles list and grant the intended role explicitly if appropriate.
The group was chosen but no approval card arrived. Confirm the service is running and post /start@{{bot_username}} connect in the group. The card is delivered to an eligible owner/admin DM, not to the group.
The second bot never comes online.TELEGRAM_INSTANCES and TELEGRAM_BOT_TOKEN_<NAME> are read once at start, so restart after adding a bot. A name whose token equals one already in use is skipped with a warning in logs/nanoclaw.error.log (Telegram allows one poller per token): give each bot its own BotFather token. A pairing code issued for telegram-<name> is ignored by the first bot; send it to the new one.
Everything green but no replies. Run pnpm exec vitest run src/channels/telegram-registration.test.ts — red means the barrel import or the @chat-adapter/telegram install drifted, so re-run the Apply steps. If green, restart again (bash setup/lib/restart.sh) and check logs/nanoclaw.error.log for token errors.
How do I install add-telegram?
Download .claude/skills/add-telegram/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does add-telegram live?
The publisher keeps it at https://github.com/nanocoai/nanoclaw.
Which agents can use add-telegram?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.