Files

Alejandro Gutiérrez fe9285351b feat: add Telegram connector package for mesh-to-chat bridging

Introduces @claudemesh/connector-telegram — a standalone bridge process
that joins a mesh as peerType: "connector" and relays messages
bidirectionally between a Telegram chat and mesh peers via long polling.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-07 23:52:00 +01:00

2.8 KiB

Raw Permalink Blame History

@claudemesh/connector-telegram

Bridges a Telegram chat and a claudemesh mesh, relaying messages bidirectionally. Joins the mesh as peerType: "connector", channel: "telegram".

Setup

1. Create a Telegram bot

Open Telegram, search for @BotFather
Send /newbot, follow the prompts
Copy the bot token (e.g. 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

2. Get the chat ID

Add your bot to a group chat (or start a DM with it)
Send a message in the chat
Fetch updates to find the chat ID:
```
curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates | jq '.result[0].message.chat.id'
```
Group IDs are negative numbers (e.g. -1001234567890). DM IDs are positive.

3. Get mesh credentials

You need a claudemesh membership. Use the CLI to join a mesh and note the credentials, or check your mesh config file (~/.config/claudemesh/config.json).

4. Configure environment variables

Variable	Description	Example
`TELEGRAM_BOT_TOKEN`	Bot token from @BotFather	`123456:ABC-DEF...`
`TELEGRAM_CHAT_ID`	Target chat ID	`-1001234567890`
`BROKER_URL`	Broker WebSocket URL	`wss://ic.claudemesh.com/ws`
`MESH_ID`	Mesh UUID	`abc123-...`
`MEMBER_ID`	Member UUID	`def456-...`
`PUBKEY`	Ed25519 public key (hex)	`a1b2c3...`
`SECRET_KEY`	Ed25519 secret key (hex)	`d4e5f6...`
`DISPLAY_NAME`	Peer display name (optional)	`Telegram-DevChat`

5. Run

# Build
npm run build

# Start
TELEGRAM_BOT_TOKEN=... TELEGRAM_CHAT_ID=... BROKER_URL=wss://ic.claudemesh.com/ws \
  MESH_ID=... MEMBER_ID=... PUBKEY=... SECRET_KEY=... DISPLAY_NAME=Telegram-DevChat \
  npm start

Or with npx (once published):

TELEGRAM_BOT_TOKEN=... npx @claudemesh/connector-telegram

How it works

Telegram -> Mesh: Text messages from Telegram are formatted as [SenderName] message and broadcast to all mesh peers.
Mesh -> Telegram: Messages from mesh peers are formatted as <b>[PeerName]</b> message (HTML) and posted to the Telegram chat.
Non-text messages (photos, stickers, etc.) are skipped with a log note.
The connector uses long polling (no webhooks needed, no public URL required).
Auto-reconnects to the mesh broker with exponential backoff.

Architecture

Telegram Chat  <--long poll-->  TelegramClient
                                     |
                                  Bridge (relay)
                                     |
Mesh Broker   <----WebSocket---->  MeshClient

src/config.ts — Configuration types and env loader
src/telegram.ts — Telegram Bot API client (fetch + long polling)
src/mesh-client.ts — Minimal claudemesh WS client (tweetnacl for ed25519 signing)
src/bridge.ts — Bidirectional message relay
src/index.ts — Entry point, wires everything together

2.8 KiB Raw Permalink Blame History