TikTok Downloader Telegram Bot

A Telegram bot that downloads TikTok videos and slideshows from shared links and sends them back as media. Supports both direct chat messages and inline mode.

Features

• Download TikTok videos from vm.tiktok.com / vt.tiktok.com / full URLs
• Convert photo slideshows into a short video with gallery-dl + ffmpeg
• Reply in private/group chats and serve results via inline queries
• Enforce Telegram’s ~50 MB upload limit with a clear error message
• Persist inline video filenames in SQLite
• Log to file, console, and optionally forward errors to a Telegram chat
• Clean up temporary video files after sending
• Unit tests for URL parsing, page JSON extraction, size limits, and SQLite (pytest)

Tech stack

Layer	Technology
Bot API	pyTelegramBotAPI (TeleBot)
Scraping	BeautifulSoup4 + requests
Slideshows	gallery-dl, ffmpeg
Storage	SQLite
Config	python-dotenv
Tests	pytest
Language	Python 3

Getting started

Prerequisites

• Python 3.10+ recommended
• A Telegram bot token from @BotFather
• Mozilla-format cookies.txt exported for tiktok.com (required for downloads)
• System tools on PATH:
  • ffmpeg
  • gallery-dl (slideshows only)
• A configured file server (e.g. nginx) that publicly serves files from VIDEO_PATH over HTTPS — required for inline mode. Direct chat downloads work without it.

Install

python -m venv venv

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

pip install -r requirements.txt

Configure

cp .env.example .env

Edit .env and set at least:

BOT_TOKEN=your-telegram-bot-token
LOGS_CHAT_ID=your-telegram-chat-id

Place your TikTok cookies in cookies.txt (or change COOKIES_PATH).

Optional paths and public URLs for inline mode:

Variable	Purpose
VIDEO_PATH	Where downloaded videos are stored temporarily
SLIDE_PATH	Working directory for slideshow assets
THUMBNAIL_URL	Preview image for inline results
SERVER_VIDEO_PATH	Public base URL that serves files from VIDEO_PATH

Inline mode requires a file server. Telegram fetches inline videos from a public HTTPS URL (SERVER_VIDEO_PATH), so you must expose VIDEO_PATH through a web server (for example nginx). Without that setup, only regular chat messages work.

Run

python tiktok_downloader.py

Send a TikTok link to the bot in a chat, or use it inline (@YourBot <url>).

Run tests

pip install -r requirements.txt
pytest

The suite covers TikTok URL extraction, invalid-redirect detection, rehydration JSON / media URL parsing, the Telegram size limit check, and SQLite insert / fetch behavior.

Project structure

.
├── tiktok_downloader.py   # Bot handlers, download & slideshow pipeline
├── tiktok_core.py         # Pure URL / HTML helpers (unit-tested)
├── bot_logger.py          # File / console / Telegram error logging
├── db_init.py             # SQLite helpers for inline video IDs
├── tests/                 # Unit tests (pytest)
├── requirements.txt
├── pytest.ini
├── .env.example
├── cookies.txt            # Local only (gitignored)
├── videos/                # Temporary downloads (gitignored)
└── slides/                # Slideshow working files (gitignored)

Architecture

1. Message / inline handlers in tiktok_downloader.py resolve short TikTok URLs and choose video vs slideshow flow.
2. HTML scrape (get_tiktok_json) reads __UNIVERSAL_DATA_FOR_REHYDRATION__ and picks a playable media URL.
3. Slideshow path uses gallery-dl to fetch images/audio, then ffmpeg to build an MP4.
4. SQLite (db_init.py) stores filenames so inline results get stable IDs.
5. Logging (bot_logger.py) writes locally and can push ERROR events to a Telegram chat.

TODO

• Support YouTube Shorts
• Support Instagram Reels

License

MIT — see LICENSE.