claudemesh/packages/connector-telegram

@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

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

2. Get the chat ID

1. Add your bot to a group chat (or start a DM with it)
2. Send a message in the chat
3. 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