Telegram Clone Worker

Fast, serverless Telegram channel cloner, batch backfiller, and real-time live synchronization engine.
Runs natively on Cloudflare Workers, Cloudflare D1 (Serverless SQLite), and the Telegram Bot API.

Telegram Clone Worker is a self-hosted, cloud-native Telegram management engine and web console designed to replicate message history between Telegram channels and groups at maximum speed, while staying completely within Telegram's rate limits and Cloudflare's free-tier boundaries.

Whether you need to migrate an archive of 100,000+ historical media files, maintain a real-time live mirror of an active broadcast channel, or selectively forward specific media types (videos, documents, audio) above a certain file size threshold, Telegram Clone Worker handles it all automatically in the background.

Real-time dashboard tracking active pipelines, messages copied counter, and multi-bot metrics.

Granular task view showing backfill progress, live auto-sync polling status, and channel bindings.

• Sequential Range Backfill: Clone full history between exact message IDs (start_id to end_id) with configurable pacing batch sizes (default: 60 messages/minute).
• "Last N" Recent Backfill: Fast backward-scanning discovery to clone the latest N messages without needing to guess channel start IDs.
• Resilient Gap Handling: Deleted posts or empty message IDs in Telegram channels are skipped cleanly without stalling the pipeline or throwing false failures.

• Cron-Driven Polling: Automatically checks Telegram updates every minute across all active bots with multi-page update draining (up to 500 updates per tick).
• Two-Stage Catch-Up Stream: Buffers incoming live messages while an initial history backfill is active, and automatically drains the buffer in sequential order once the backfill finishes.

• Media Type Filtering: Choose to copy all messages or restrict to specific media types (document, video, photo, audio).
• File Size Thresholds: Filter media by file size (e.g. only copy files ≥ 10 MB or ignore files > 500 MB).
• Live Filter Telemetry: See real-time skip and match logs directly in your activity feed.

• Concurrency Limiter: Multi-bot polling strictly adheres to Cloudflare Workers' 6-connection ceiling, preventing silent socket stalls.
• Atomic Bot Leases: Bot-scoped locks guarantee tasks on the same bot never collide or flood Telegram with parallel batches.
• Automatic 429 Cooldown: Catches Telegram rate limits (retry_after), pauses the specific bot, and automatically resumes once the cooldown expires.
• 401 & 409 Self-Healing:
  • Automatically detects revoked tokens (401 Unauthorized), pauses the affected task, and logs actionable alerts.
  • Automatically detects and resolves Telegram webhook conflicts (409 Conflict) by calling deleteWebhook on the fly.

• Built with React 19, Vite, and tokenized CSS.
• Zero Duplication Information Architecture: Single unified view for Historical Backfill progress, Live Auto-Sync metrics, and Task Specifications.
• Diagnostic Hub: Send ad-hoc test copies directly from the console to verify bot permissions before running bulk tasks.
• Task Templates: Save source/destination configurations to clone new tasks in seconds.
• Responsive Layout: Docked bottom footer on desktop/tablet views and touch-friendly mobile drawer.
• Fail-Safe Error Boundary: React crashes are caught gracefully with intuitive recovery actions instead of blank screens.

• Zero-Friction Master Password: Protect your web console by defining an optional ADMIN_PASSWORD secret in Cloudflare or setting one via the browser on first launch.
• Open Access Mode: If you prefer an open console, simply tap "Proceed without password". You can secure it at any time directly from the console navigation.
• Stateless Web Crypto Sessions: HMAC-SHA256 signed bearer tokens validated in < 0.05ms CPU with zero D1 database reads/writes, adding 0 overhead to the 4-second polling loops.

flowchart LR
    subgraph Telegram ["Telegram Infrastructure"]
        TG_API["Telegram Bot API"]
        SRC_CHAT["Source Channel"]
        DST_CHAT["Destination Channel"]
    end

    subgraph Cloudflare ["Cloudflare Workers Platform"]
        CRON["Scheduled Cron (1 min)"]
        HTTP["HTTP Fetch Handler"]
        WORKER["Telegram Clone Worker Engine"]
        D1[("Cloudflare D1 (SQLite)\n• bots\n• tasks\n• activity_log\n• pending_buffer")]
        ASSETS["Static Web Assets (React 19 SPA)"]
    end

    subgraph Client ["Browser Console"]
        UI["Web Dashboard"]
    end

    CRON -->|Trigger| WORKER
    HTTP -->|API Requests| WORKER
    WORKER <-->|Query & Mutate| D1
    WORKER <-->|getUpdates / copyMessages| TG_API
    TG_API -->|Read| SRC_CHAT
    TG_API -->|Post| DST_CHAT
    UI <-->|Manage Tasks & Telemetry| HTTP
    UI <-->|Load UI| ASSETS

Deploy your own instance of Telegram Clone Worker with a single click:

1. Click the Deploy with Workers button above.
2. Sign in to your Cloudflare account and authorize GitHub.
3. Cloudflare will automatically:
   • Fork/clone this repository to your account.
   • Provision a new Cloudflare D1 database (telegram-clone-worker-db).
   • Deploy the Worker and static assets.
4. Activate Your Worker URL (One-time, 1-Click in Cloudflare Dashboard):
   • When Cloudflare creates a new Worker from a connected Git repository, it allocates your unique subdomain (telegram-clone-worker.<your-subdomain>.workers.dev) with the route initially set to Disabled by default for safety.
   • To activate your public URL:
     1. In your Cloudflare Dashboard, open Workers & Pages and click telegram-clone-worker.
     2. Click the Domains tab in the top navigation bar (or click Domains and routes → on the right sidebar).
     3. Under the workers.dev section, click Enable.
     4. Your Worker URL is now live (https://telegram-clone-worker.<your-subdomain>.workers.dev).
     5. This is a one-time step — all future code pushes and updates will remain permanently live at this URL!
   • (Optional) You can also click Add custom domain in the same Domains tab to serve the application on your own branded domain (e.g. clone.yourdomain.com).
5. Zero-Config Database Initialization:
   • The worker features an automatic bootstrap engine (src/db/bootstrap.ts).
   • When you visit your deployed worker URL for the first time, all tables and indexes are created automatically. You do not need to run any manual terminal migration commands!
6. Configuring Admin Password (Optional):
   • Via Cloudflare Dashboard: Go to Workers & Pages > telegram-clone-worker > Settings > Variables and Secrets, and add a secret named ADMIN_PASSWORD. When set, the console strictly requires this password to log in.
   • Via CLI: Run npx wrangler secret put ADMIN_PASSWORD in your terminal.
   • Via Browser: If you do not configure ADMIN_PASSWORD, opening the console for the first time will ask if you want to set an admin password or proceed with open access. You can protect or unprotect your console at any time.

When new features or bug fixes are released upstream, you can update your deployment in seconds:

git pull https://github.com/iamLiquidX/telegram-clone-worker.git main
git push origin main

Because Cloudflare Workers Builds is connected to your repository, pushing to main automatically triggers Cloudflare to build and redeploy the latest version to your live URL!

If you prefer to run or customize the project locally:

• Node.js (v20 or higher)
• npm
• Cloudflare Wrangler CLI (npm install -g wrangler)

git clone https://github.com/iamLiquidX/telegram-clone-worker.git
cd telegram-clone-worker
npm install

npx wrangler d1 create telegram-clone-worker-db

Copy the database_id from Wrangler's output and update it in wrangler.jsonc:

"d1_databases": [
  {
    "binding": "DB",
    "database_name": "telegram-clone-worker-db",
    "database_id": "your-database-uuid-here"
  }
]

# For local development
npm run db:migrate:local

# For remote Cloudflare database
npm run db:migrate:remote

npm run dev

Open http://localhost:5173 in your browser.

npm run deploy

All API endpoints run under the /api route:

• Author: iamLiquidX
• Support Chat: Telegram Community
• Source Code: GitHub Repository
• License: MIT