/add-telegram

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):

src/channels/telegram.ts
src/channels/telegram-pairing.ts
src/channels/telegram-pairing.test.ts
src/channels/telegram-registration.test.ts
src/channels/telegram-connect-group.test.ts
src/channels/telegram-instances-registration.test.ts
src/channels/telegram-pairing-interceptor.test.ts

2. Register the adapter

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:

'pair-telegram': () => import('./pair-telegram.js'),

4. Install the adapter package

Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:

@chat-adapter/telegram@4.41.1

5. Build and validate

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

[ "{{has_default_bot}}" = yes ] && echo ask || 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:

curl -sf https://api.telegram.org/bot{{bot_token}}/getMe | jq -er '.result.username'

Add another bot

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: