TeleFlow-Backend

Open-source REST API backend for Telegram UserBot via MTProto

Overview

TeleFlow-Backend provides a complete REST API, OpenAPI documentation, Webhooks, and Event Streaming to control Telegram User Accounts (UserBot) through MTProto — without directly using GramJS, Telethon, or Pyrogram.

Features

🔌 REST API — Complete HTTP API for all Telegram operations
📖 OpenAPI 3.1 — Full Swagger documentation at /docs
🔗 Webhooks — Event-driven notifications with retry & signature verification
⚡ WebSocket & SSE — Real-time event streaming
🔐 Authentication — JWT + API Key with role-based access
📱 Multi-Session — Manage multiple Telegram accounts simultaneously
🐳 Docker Ready — One-command deployment
🏗️ Production Ready — Structured logging, health checks, graceful shutdown

Tech Stack

Component	Technology
Runtime	Node.js 22 LTS
Language	TypeScript
Framework	Fastify
Telegram	GramJS (MTProto)
Validation	Zod
ORM	Prisma
Database	SQLite (default)
Logging	Pino
Docs	OpenAPI 3.1 + Swagger UI

Quick Start

Prerequisites

Node.js >= 22
Telegram API credentials from my.telegram.org

Installation

# Clone
git clone https://github.com/your-org/TeleFlow-Backend.git
cd TeleFlow-Backend

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with your Telegram API credentials

# Setup database
npx prisma db push

# Start development server
npm run dev

Docker

# Using Docker Compose
cp .env.example .env
# Edit .env with your credentials

docker compose up -d

Docker (GHCR)

docker pull ghcr.io/your-org/teleflow-backend:latest

docker run -d \
  -p 3000:3000 \
  -e JWT_SECRET=your-secret \
  -e API_KEY=your-api-key \
  -e SESSION_ENCRYPTION_KEY=your-encryption-key \
  -e TELEGRAM_API_ID=your-api-id \
  -e TELEGRAM_API_HASH=your-api-hash \
  -v teleflow_data:/app/data \
  ghcr.io/your-org/teleflow-backend:latest

API Overview

Once running, visit http://localhost:3000/docs for full interactive API documentation.

Health

GET /health          # Health check
GET /version         # Version info

Authentication

POST /api/v1/auth/login     # Get API key & JWT
POST /api/v1/auth/logout    # Revoke access
GET  /api/v1/auth/me        # Current user info

Sessions

GET    /api/v1/sessions              # List sessions
POST   /api/v1/sessions              # Create session (start login)
GET    /api/v1/sessions/:id          # Get session
DELETE /api/v1/sessions/:id          # Delete session
POST   /api/v1/sessions/:id/connect  # Reconnect session
POST   /api/v1/sessions/:id/disconnect  # Disconnect
POST   /api/v1/sessions/verify-code     # Verify phone code
POST   /api/v1/sessions/verify-password # Verify 2FA
POST   /api/v1/sessions/import          # Import session string
POST   /api/v1/sessions/:id/export      # Export session string

Messages

POST /api/v1/messages/send      # Send message
POST /api/v1/messages/reply     # Reply to message
POST /api/v1/messages/edit      # Edit message
POST /api/v1/messages/delete    # Delete messages
POST /api/v1/messages/forward   # Forward messages
POST /api/v1/messages/react     # React to message
POST /api/v1/messages/pin       # Pin message
POST /api/v1/messages/unpin     # Unpin message
POST /api/v1/messages/read      # Mark as read
GET  /api/v1/messages/history   # Get message history

Chats

GET  /api/v1/chats               # List chats
GET  /api/v1/chats/:id           # Get chat info
POST /api/v1/chats/join          # Join chat
POST /api/v1/chats/leave         # Leave chat
GET  /api/v1/chats/:id/members   # Get members
POST /api/v1/chats/search        # Search messages

Webhooks

GET    /api/v1/webhooks       # List webhooks
POST   /api/v1/webhooks       # Create webhook
PUT    /api/v1/webhooks/:id   # Update webhook
DELETE /api/v1/webhooks/:id   # Delete webhook

Events

GET /api/v1/events    # SSE stream
GET /api/v1/ws        # WebSocket

Configuration

Variable	Description	Default
`PORT`	Server port	`3000`
`HOST`	Server host	`0.0.0.0`
`NODE_ENV`	Environment	`development`
`JWT_SECRET`	JWT signing secret	required
`API_KEY`	Default API key	required
`DATABASE_URL`	Database connection	`file:./teleflow.db`
`SESSION_ENCRYPTION_KEY`	Session encryption key	required
`TELEGRAM_API_ID`	Telegram API ID	required
`TELEGRAM_API_HASH`	Telegram API Hash	required
`LOG_LEVEL`	Log level	`info`
`CORS_ORIGIN`	CORS origin	`*`
`RATE_LIMIT_MAX`	Rate limit max requests	`100`
`RATE_LIMIT_WINDOW_MS`	Rate limit window (ms)	`60000`

Event Types

TeleFlow defines 28 event types across 6 categories. Subscribe to specific events or use the * wildcard to receive all of them. Webhooks deliver a signed POST for every matching event with automatic retry (3 attempts, exponential backoff).

Session Events

Event	Description	Status
`session.created`	Login flow started, code sent to phone	✅ Dispatched
`session.connected`	Session connected to MTProto	✅ Dispatched
`session.disconnected`	Session disconnected	✅ Dispatched
`session.authorized`	Login (code or 2FA password) succeeded	✅ Dispatched
`session.deleted`	Session removed	✅ Dispatched

Message Events

Event	Description	Status
`message.received`	New incoming message (via GramJS NewMessage)	✅ Dispatched
`message.sent`	Outgoing message sent via API	✅ Dispatched
`message.edited`	Message edited via API	✅ Dispatched
`message.deleted`	Message(s) deleted via API	✅ Dispatched
`message.read`	Chat marked as read via API	✅ Dispatched

Chat Events

Event	Description	Status
`chat.created`	New chat/dialog appeared	✅ Dispatched (incoming updates)
`chat.updated`	Chat metadata changed	✅ Dispatched (incoming updates)
`chat.deleted`	Chat removed	✅ Dispatched (incoming updates)
`chat.member_joined`	Member joined a chat	✅ Dispatched (incoming + join API)
`chat.member_left`	Member left a chat	✅ Dispatched (incoming + leave API)

Group Events

Event	Description	Status
`group.created`	New group created	✅ Dispatched (incoming updates)
`group.updated`	Group settings changed	✅ Dispatched (incoming updates)
`group.deleted`	Group deleted	✅ Dispatched (incoming updates)
`group.member_added`	Member added to group	✅ Dispatched (incoming + join API)
`group.member_removed`	Member removed from group	✅ Dispatched (incoming + leave API)
`group.admin_changed`	Group admin rights changed	✅ Dispatched (incoming updates)

Channel Events

Event	Description	Status
`channel.created`	New channel created	✅ Dispatched (incoming updates)
`channel.updated`	Channel settings changed	✅ Dispatched (incoming updates)
`channel.deleted`	Channel deleted	✅ Dispatched (incoming updates)
`channel.post_published`	New post published in channel	✅ Dispatched (UpdateNewChannelMessage)

User Events

Event	Description	Status
`user.status_changed`	User online/offline status changed	✅ Dispatched (incoming updates)
`user.typing`	User started typing	✅ Dispatched (incoming updates)
`user.profile_updated`	User profile info changed	✅ Dispatched (incoming updates)

✅ Dispatched = event is wired and fires end-to-end (session lifecycle + API-triggered message operations + incoming messages). ✅ Dispatched = wired end-to-end. Session + Message events fire from API calls AND incoming GramJS updates. Chat/Group/Channel/User events fire from incoming MTProto updates (join/leave/admin/typing/status/profile/channel post).

Webhook Payload

Every webhook delivery includes a signed POST body:

{
  "id": "V1StGXRK_ZYdJsl",
  "type": "message.received",
  "sessionId": "cmqz4sw0f...",
  "timestamp": "2026-06-29T20:30:09.222Z",
  "data": { ... }
}

Headers sent:

Header	Description
`X-TeleFlow-Event`	Event type (e.g. `message.sent`)
`X-TeleFlow-Delivery-Id`	Unique delivery ID for idempotency
`X-TeleFlow-Signature`	HMAC-SHA256 hex of body (only if `secret` set)

Verify signature:

const crypto = require('crypto');
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
// Compare with X-TeleFlow-Signature header (timing-safe)

Retry policy: 3 attempts with backoff 1s → 3s → 10s. Delivery records (status, response, duration, attempts) are stored in the webhook_deliveries table.

Error Format

All errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "MESSAGE_NOT_FOUND",
    "message": "Message not found"
  }
}

Architecture

Client → REST API → Controllers → Services → Telegram Adapter → GramJS → MTProto

Project Structure

src/
├── config/         # Environment configuration
├── controllers/    # Route handlers
├── database/       # Prisma client
├── events/         # Event dispatcher
├── middlewares/     # Auth, error handling
├── plugins/        # Fastify plugins
├── routes/         # Route definitions
├── schemas/        # Zod validation schemas
├── services/       # Business logic
├── telegram/       # GramJS adapter
├── types/          # TypeScript types
├── utils/          # Logger, crypto, errors
├── webhooks/       # Webhook delivery
├── server.ts       # Fastify server setup
└── index.ts        # Entry point

License

Apache License 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github/workflows		.github/workflows
assets		assets
prisma		prisma
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
openapi.json		openapi.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

TeleFlow-Backend

Overview

Features

Tech Stack

Quick Start

Prerequisites

Installation

Docker

Docker (GHCR)

API Overview

Health

Authentication

Sessions

Messages

Chats

Webhooks

Events

Configuration

Event Types

Session Events

Message Events

Chat Events

Group Events

Channel Events

User Events

Webhook Payload

Error Format

Architecture

Project Structure

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages