Downloader Bot: save TikTok and YouTube videos via Telegram

The task

To keep a video you liked, you normally have to go to a download site: sit through ads, dodge redirects, save the file to your phone's downloads and then dig it out of a file manager to forward it to a friend. TikTok adds a watermark on top. Online tools break regularly, demand payment or funnel traffic into advertising.

What was needed was a bot for downloading videos from TikTok, YouTube and Instagram that lives where the conversation already is: drop a link into the chat and get the file back in the same chat. It can be forwarded to anyone immediately, because it is already inside Telegram.

The solution

Downloader Bot is an in-house Telegram bot, version 2.6.3. Implemented:

• Platforms. TikTok without the watermark, YouTube and Shorts, Instagram Reels and posts, TikTok photo slideshows (stitched into mp4), VK Video, X (Twitter), Reddit, Pinterest, Twitch, SoundCloud, Vimeo, Coub, Yandex Video. Separately, for admins only, Hi-Res music from Qobuz, Deezer and Tidal through the ToshaMusic engine.
• Quality choice. From 240p to 4K; the file size is shown on the button in advance.
• Audio extraction. MP3 with cover art and metadata; the bitrate follows the best audio track of the video, from 192 to 320 kbps.
• Instant repeats. Anything already downloaded is served by file_id without re-downloading.
• Live progress. A progress bar, speed and time remaining.
• Getting past the 50 MB limit. Automatic ffmpeg compression or splitting into parts; up to 2000 MB with a local Bot API.
• Cookies. Age-restricted and private videos, YouTube's "Sign in to confirm" check; the file is uploaded through the admin panel.
• Default format. The /format command: download immediately, no questions asked.
• Admin panel. Summary, analytics by platform and by day, users, moderation, broadcasts with a delivery report, cookies, settings on the fly, logs, maintenance.

The link does not have to be a separate message: the bot finds it inside any text.

How it works

yt-dlp as the universal engine

yt-dlp is an open-source library that can fetch video and audio from hundreds of sites. The bot probes a link once, gets the list of formats with sizes and reuses that result for the download, saving a network request. New platforms are added by recognising the domain: Vimeo and Coub went the same route as Reddit or Twitch, with no dedicated code. yt-dlp and ffmpeg run in separate threads and processes, so the bot keeps answering other users while someone's video is downloading; a semaphore caps the number of concurrent downloads.

TikTok without the watermark

TikTok is fetched through a direct API that serves the video without the embedded mark. TikTok photo posts (slideshows) are something yt-dlp cannot handle at all: the bot itself stitches the images and the post's music into one mp4 with ffmpeg, giving each image an equal share of the total duration and normalising different aspect ratios to 1080×1920.

PO tokens and YouTube link signing

YouTube protects its media links with two mechanisms, neither of which belongs to the bot's code. Link signatures are computed by YouTube's own obfuscated JavaScript, so a JS runtime is required: Deno, built into the image. The second mechanism is the PO token, a session token tied to a browser; it is issued by a separate service that runs alongside the bot in docker-compose and is not exposed externally. Without Deno, video fails; without tokens, audio fails, and in both cases metadata still loads fine, so the error only appears after the quality button is pressed. YouTube changes its protection regularly, so the first step on failures is to update yt-dlp.

Getting past the 50 MB limit: local Bot API

Telegram's cloud Bot API does not let a bot send files over 50 MB. The bot shows the size of every quality before downloading, flags what is over the limit but compressible and what cannot be saved at all, aborts a download that could never be sent, and recompresses through ffmpeg, lowering the resolution when needed. If the quality would become unacceptable, the bot offers to split the file into parts. For files up to 2000 MB, docker-compose describes a local Bot API server (the bigfiles profile): in local mode it returns a path on disk instead of a URL, and the bot gets access to the same files.

file_id cache

Every file uploaded to Telegram once receives a file_id identifier. The bot stores it in SQLite and, on a repeated link, forwards the file instantly with no traffic. The cache lifetime is configurable, 30 days by default.

Cookies and the admin panel

Cookies are needed for age-restricted and private videos and for YouTube's "Sign in to confirm" check. A cookies.txt file is uploaded through the admin panel; the bot validates the Netscape format and shows how fresh each file is. The admin panel runs on inline buttons under the message: summary, analytics by platform and by day, top errors, users with search, bans with a reason, broadcasts with preview and report, limits and maintenance mode, logs, server status, cache cleanup, database export. Users who blocked the bot are removed from the database automatically after a broadcast.

Results

• Link in, file out: no download sites, ads or watermarks.
• 12 platforms plus Hi-Res music for admins.
• Quality from 240p to 4K, MP3 with cover art, file size known before downloading.
• Files over 50 MB are compressed, split, or sent whole through the local Bot API up to 2000 MB.
• Repeated links are served from the cache without re-downloading.
• A stalled link is cut off by a timeout with a clear error rather than an endless "Reading link".
• The fast test suites (unit tests and routing with a fake Telegram) need no network; a separate flag runs a live download from YouTube.

Technologies and why

• Python 3.14 and aiogram 3: an asynchronous bot, inline keyboards, anti-flood and maintenance mode in middleware.
• yt-dlp: the universal download engine; the bgutil-ytdlp-pot-provider plugin for YouTube PO tokens.
• Deno: the JS runtime for YouTube link signing, built into the image.
• FFmpeg: merging, MP3, compression, splitting, thumbnails, slideshow assembly.
• SQLite (aiosqlite): users, log, file_id cache, settings.
• aiohttp: client for the TikTok API and the Hi-Res engine.
• Local Bot API (telegram-bot-api): an optional profile for files up to 2000 MB.
• Docker Compose: the bot and the PO token service; the bigfiles, hires and ruproxy profiles are enabled by flag.

Status

In-house product, in production. The current version is 2.6.3 from 27 September 2026. September additions: TikTok photo slideshows (2.3.0), a Hi-Res music section through the separate ToshaMusic service (2.4.0), honest MP3 bitrate based on the source track (2.4.1), accurate YouTube size estimates without HLS duplicates (2.4.2), Vimeo and Coub (2.5.0), the "Made in DevUnit Lab" signature (2.6.0), a metadata probe timeout (2.6.1), Yandex Video through a SOCKS5 tunnel with a Russian exit (2.6.2) and cookies for its anti-bot check (2.6.3).

Limitations: YouTube changes its protection regularly, so yt-dlp is updated first on failures; Instagram without cookies often returns an empty response; there are no guarantees for Yandex Video. Tests are run manually, there is no CI.