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