lingxi-web/telegram-gateway/README.md

Telegram User Account Gateway

A production-grade REST API + Webhook gateway for managing Telegram user accounts via TDLib (not Bot API). Supports multi-tenant, multi-account management with independent proxies, message queue, rate limiting, and audit logging.

Architecture

• Runtime: Node.js 20+ with TypeScript
• Framework: NestJS 11.x
• Database: PostgreSQL 16 (TypeORM)
• Cache/Queue: Redis 7 + BullMQ
• TDLib: tdjson via worker_threads
• Auth: JWT (Bearer tokens)
• API Docs: Swagger at /api/docs

Quick Start

# Copy environment config
cp .env.example .env

# Start infrastructure
docker-compose -f docker/docker-compose.yml up -d postgres redis

# Install dependencies
npm install

# Run migrations
npm run migration:run

# Start development server
npm run start:dev

Docker Compose

# Start all services
docker compose --env-file .env -f docker/docker-compose.yml up -d --build

See DEPLOYMENT.md for production setup, readiness checks, persistent data, and Windows WSL requirements.

When used by 灵犀跨境, also read the repository-level integration guide.

API Endpoints

Admin

• GET /api/admin/health - Health check (public)
• GET /api/admin/metrics - Application metrics
• GET /api/admin/status - TDLib client status

Auth

• POST /api/auth/register - Register user (public)
• POST /api/auth/login - Login (public)

Tenants

• POST /api/tenants - Create tenant
• GET /api/tenants - List tenants
• GET /api/tenants/:id - Get tenant
• PUT /api/tenants/:id - Update tenant
• DELETE /api/tenants/:id - Delete tenant

TG Accounts

• POST /api/tg-accounts - Create Telegram account
• GET /api/tg-accounts - List accounts
• GET /api/tg-accounts/:id - Get account
• DELETE /api/tg-accounts/:id - Remove account

TG Account Authorization

• POST /api/tg-accounts/:id/auth/phone - Set phone number
• POST /api/tg-accounts/:id/auth/code - Submit verification code
• POST /api/tg-accounts/:id/auth/password - Submit 2FA password
• POST /api/tg-accounts/:id/auth/logout - Logout

Chats & Messages

• GET /api/tg-accounts/:id/chats - List chats
• GET /api/tg-accounts/:id/chats/:chatId/history - Chat history
• POST /api/tg-accounts/:id/messages/send - Send message (queued)
• POST /api/tg-accounts/:id/messages/send-direct - Send message (direct)
• POST /api/tg-accounts/:id/messages/pin - Pin a message
• POST /api/tg-accounts/:id/messages/unpin - Unpin a message
• POST /api/tg-accounts/:id/messages/action - Send typing/chat action
• GET /api/tg-accounts/:id/messages/:chatId/:messageId/link - Get message link

Contacts, Sessions & Groups

• GET /api/tg-accounts/:id/contacts/search?q=... - Search by phone, username, or general query
• GET /api/tg-accounts/:id/dialogs/sessions - List active Telegram sessions
• POST /api/tg-accounts/:id/dialogs/sessions/:sessionId/terminate - Terminate session
• POST /api/tg-accounts/:id/dialogs/users/:userId/block - Block user
• POST /api/tg-accounts/:id/dialogs/users/:userId/unblock - Unblock user
• POST /api/tg-accounts/:id/groups/join-by-invite-link - Join via invite link
• PUT /api/tg-accounts/:id/groups/:chatId/title - Change group title
• PUT /api/tg-accounts/:id/groups/:chatId/photo - Change/remove group photo

Webhooks

• POST /api/tg-accounts/:id/webhooks - Create webhook
• GET /api/tg-accounts/:id/webhooks - List webhooks

Operations

• GET /api/admin/audit-logs - Query tenant-scoped audit logs
• GET /api/admin/audit-logs/accounts/:accountId - Query account audit logs
• GET /api/admin/rate-limits/:accountId - Get account rate-limit statistics

Environment Variables

See .env.example for all available configuration options.

License

MIT