--- 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](https://github.com/averygan/reclip) and yt-dlp. Send a link, pick your format and quality, get the file delivered right in the chat. ![Bot conversation](images/bot.png) ## 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) ![Admin dashboard](images/admin.png) ## 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](https://t.me/BotFather)) - Telegram API credentials (from [my.telegram.org](https://my.telegram.org)) ### Setup 1. Clone this repository: ```bash git clone https://github.com/gth-ai/reclip-telegram-bot.git cd reclip_bot ``` 2. Copy the example environment file: ```bash cp .env.example .env ``` 3. Edit `.env` with your credentials: ```bash 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: ```bash 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`: ```yaml 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) ```bash # 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](https://github.com/averygan/reclip) by averygan - The media download engine - [yt-dlp](https://github.com/yt-dlp/yt-dlp) - The download backend - [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) - Telegram bot framework ## License MIT