README.md

metadata

title: Reclip Telegram Bot
emoji: 📥
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false

ReClip Telegram Bot

A self-hosted Telegram bot that downloads media from YouTube, TikTok, Instagram, Twitter, Reddit, and 1000+ other sites. Powered by reclip and yt-dlp.

Send a link, pick your format and quality, get the file delivered right in the chat.

Features

• Multi-platform support (YouTube, TikTok, Instagram, Twitter, Reddit, and 1000+ more via yt-dlp)
• Format selection (MP4 video or MP3 audio)
• Quality picker with all available resolutions
• Real-time download progress (percentage)
• Thumbnail preview with metadata (title, platform, duration)
• Files up to 2GB via self-hosted Telegram Bot API
• Automatic file cleanup (configurable age and disk limits)
• Concurrent download limiting (prevents resource exhaustion)
• Admin dashboard with download stats, history, error tracking, and disk management
• Web UI included (reclip's built-in web interface)

Architecture

Telegram User ──> Self-hosted Bot API (2GB limit)
                        │
                        ▼
                   bot (python-telegram-bot + httpx)
                   │              │
          HTTP     │              │  HTTP events
                   ▼              ▼
              reclip (Flask)   dashboard (FastAPI)
              port 8899        port 8080
                               │
                               ▼
                            SQLite

Four Docker containers via docker-compose:

1. reclip - Media download engine with REST API and web UI
2. bot - Telegram bot that wraps reclip's API
3. telegram-bot-api - Self-hosted Telegram Bot API server for 2GB upload limit
4. dashboard - Admin panel with download stats, history, errors, and file management

Quick Start

Prerequisites

• Docker and Docker Compose
• A Telegram bot token (from @BotFather)
• Telegram API credentials (from my.telegram.org)

Setup

1. Clone this repository:

git clone https://github.com/gth-ai/reclip-telegram-bot.git
cd reclip_bot

2. Copy the example environment file:

cp .env.example .env

3. Edit .env with your credentials:

BOT_TOKEN=your-bot-token-from-botfather
TELEGRAM_API_ID=your-api-id
TELEGRAM_API_HASH=your-api-hash

To get Telegram API credentials:

• Go to https://my.telegram.org
• Log in with your phone number
• Go to "API Development Tools"
• Create a new application (any name/description works)
• Copy the api_id and api_hash

4. Start the services:

docker-compose up -d

5. Send a video link to your bot on Telegram.

First Run Note

The self-hosted Bot API server downloads some data from Telegram on first startup. This can take a minute. The bot will start responding once the Bot API server is ready.

Configuration

All configuration is via environment variables in .env:

Variable	Default	Description
BOT_TOKEN	(required)	Telegram bot token from @BotFather
TELEGRAM_API_ID	(required)	Telegram API ID from my.telegram.org
TELEGRAM_API_HASH	(required)	Telegram API hash from my.telegram.org
MAX_CONCURRENT_DOWNLOADS	3	Max parallel downloads
CLEANUP_MAX_AGE_HOURS	1	Delete files older than this
CLEANUP_MAX_DISK_MB	5000	Max disk usage before cleanup
CLEANUP_INTERVAL_SECONDS	300	Cleanup check interval
DASHBOARD_USER	admin	Dashboard login username
DASHBOARD_PASSWORD	(required)	Dashboard login password
DASHBOARD_PORT	8080	Dashboard port on host
DASHBOARD_SECRET_KEY	change-me	Cookie signing key

Admin Dashboard

The admin dashboard is available at http://localhost:8080 after starting the services. Log in with the credentials from your .env file.

Pages:

• Dashboard — downloads today, active users, disk usage, error rate, charts
• History — full download log with filters and pagination
• Errors — failed downloads with error messages
• Admin — file management, system info, purge controls

Web UI

The reclip web UI is available if you uncomment the reclip-web service in docker-compose.yml:

reclip-web:
  extends:
    service: reclip
  ports:
    - "8899:8899"

Then access it at http://localhost:8899.

How It Works

1. You send a URL to the bot
2. Bot sends "Fetching info..." immediately
3. Bot calls reclip's API to get video metadata
4. Bot displays thumbnail, title, platform, and format buttons (MP4/MP3)
5. You tap MP4 to see quality options (1080p, 720p, etc.) or MP3 for audio
6. Bot starts the download and shows real-time progress
7. Bot uploads the file to the Telegram chat
8. Cleanup task removes old files automatically

Development

Running locally (without Docker)

# Start reclip
cd reclip && pip install flask yt-dlp && python app.py &

# Start the bot
cd bot && pip install -r requirements.txt
BOT_TOKEN=your-token RECLIP_URL=http://localhost:8899 DOWNLOADS_PATH=../reclip/downloads python bot.py

Project structure

reclip_bot/
├── docker-compose.yml      # 4 services: reclip, bot, telegram-bot-api, dashboard
├── .env.example             # Environment variables template
├── bot/
│   ├── bot.py               # Bot entry point
│   ├── handlers.py          # Telegram message/callback handlers
│   ├── reclip_client.py     # Async HTTP client for reclip API
│   ├── event_client.py      # Fire-and-forget events to dashboard
│   ├── cleanup.py           # Background file cleanup task
│   ├── requirements.txt
│   └── Dockerfile
├── dashboard/
│   ├── main.py              # FastAPI app with background tasks
│   ├── db.py                # SQLite queries (async via aiosqlite)
│   ├── auth.py              # Session cookie auth
│   ├── routes/              # API + page routes
│   ├── templates/           # Jinja2 templates (dark theme)
│   ├── static/              # CSS + Chart.js frontend
│   ├── requirements.txt
│   └── Dockerfile
└── reclip/                  # Fork of averygan/reclip with enhancements
    ├── app.py               # Flask API + web UI (with progress hooks)
    ├── Dockerfile
    ├── templates/
    └── static/

Credits

• reclip by averygan - The media download engine
• yt-dlp - The download backend
• python-telegram-bot - Telegram bot framework

License

MIT