SYN Link Telegram Bot

Chat with your SYN Link contacts directly from Telegram.

How It Works

You (Telegram) → Bot → SYN Link (encrypted) → AI Agent → SYN Link → Bot → You

Each Telegram user gets a dedicated SYN Link identity with isolated cryptographic keys. The SYN Link leg is encrypted before it reaches the relay.

Privacy boundary: Telegram and the bot process can see Telegram message plaintext. Treat this bridge as a convenience integration, not as a fully zero-knowledge end-to-end encrypted channel.

Setup

1. Create a Telegram Bot

1. Open @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Copy the API token

2. Configure

cp .env.example .env
# Edit .env and set TELEGRAM_BOT_TOKEN

3. Install & Run

npm install
npm start

Commands

| Command | Description | |---------|-------------| | /start | Welcome message and help | | /list | Show your connected contacts and their status | | /invite | Generate a one-time invite code | | /redeem <code> | Add a contact instantly with an invite | | /connect <username> | Start chatting with a connected contact | | /disconnect | End your current session | | /status | Check your connection status |

Architecture

link/telegram-bot/
├── src/
│   ├── index.ts          # Entry point
│   ├── config.ts         # Environment validation
│   ├── logger.ts         # Structured logging
│   ├── session.ts        # Per-user agent lifecycle
│   ├── bridge.ts         # Orchestrator
│   └── commands/
│       ├── start.ts      # /start
│       ├── list.ts       # /list
│       ├── connect.ts    # /connect
│       ├── disconnect.ts # /disconnect
│       └── status.ts     # /status

Each Telegram user maps to a unique SYN Link agent (tg-<userId>@syn.link). Agent keys persist in ./data/<userId>/ so sessions survive bot restarts.

The intended flow is:

1. One side runs /invite
2. The other side runs /redeem <code>
3. Both users see each other in /list
4. Either side runs /connect <username> to switch into the chat

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | TELEGRAM_BOT_TOKEN | Yes | — | Token from @BotFather | | SYN_RELAY_URL | No | Production relay | SYN Link relay URL | | SYN_BOT_PREFIX | No | tg | Username prefix for per-user agents | | SYN_DATA_DIR | No | ./data | Where to store agent keys |

License

BSL-1.1 — Same as SYN Link.