Hel_inst_bot — Unified Social Media Content Downloader for Telegram
Hel_inst_bot helps people share content from Instagram, TikTok, YouTube, X, LinkedIn, Facebook, Reddit, Threads, Pinterest, Bluesky, Vimeo, Twitch Clips and Imgur, without forcing friends to leave Telegram, register on another platform, open a blocked website, or use a VPN.
From the user's perspective, the workflow is intentionally simple: send a link and receive the media directly in Telegram. Behind that interaction is a platform-aware extraction layer that handles different post formats, authentication methods, cookie formats, media limits, captions, albums, and frequently changing social-network behavior.
The bot supports two interaction modes: direct use in a private conversation and automatic link processing inside a group where the bot is added as an administrator.
Product goal: replace inconvenient social-media links with content that can be watched, read, and forwarded immediately without leaving the current Telegram conversation.
Architecture
hel_inst_bot/ ├── hel_inst_bot.py ├── instagram_handler.py ├── tiktok_handler.py ├── youtube_handler.py ├── x_handler.py ├── linkedin_handler.py ├── facebook_handler.py ├── reddit_handler.py ├── threads_handler.py ├── pinterest_handler.py ├── bluesky_handler.py ├── vimeo_handler.py ├── twitch_handler.py ├── imgur_handler.py │ ├── cookies/ │ ├── instagram_cookies.json │ └── converted_cookies.txt │ ├── data/ │ ├── users.json │ ├── groups.json │ └── statistics.json │ ├── requirements.txt ├── .env ├── .env.example ├── README.md │ ├── bat.bat ├── restart_bot.bat ├── stop_bot.bat └── run.vbs
Each social network is isolated in its own handler, while Telegram interaction, administration, statistics, and process management remain centralized.
The recognizable Hel_inst_bot identity is preserved across the Telegram product and the portfolio presentation.
Two Interaction Modes
The bot was designed for both individual use and ongoing group conversations. The same extraction engine is used in both cases, while Telegram routing and response behavior depend on the chat context.
1Private Chat
- The user opens a direct conversation with Hel_inst_bot
- A social-media link is sent as a regular message
- The bot detects the platform and extracts the available content
- Videos, photos, albums, and publication text are returned directly in Telegram
- The user can also open the bot statistics from the interface
2Group Administrator
- Hel_inst_bot is added to a Telegram group as an administrator
- Members continue using the group normally and paste links into the conversation
- The bot recognizes supported URLs and publishes the extracted media in the same chat
- Friends can watch and forward the content without opening the original platform
- The workflow removes disruptive links from active group discussions
Supported Platforms
- Photos
- Photo carousels
- Mixed posts with photos and videos
- Reels
- Stories
- Regular video posts
🎵 TikTok
- Video extraction
- Direct delivery to Telegram
- Link normalization and platform detection
▶️ YouTube
- Regular videos up to 10 minutes
- YouTube Shorts
- Format selection suitable for Telegram delivery
🐦 X (Twitter)
- Photos
- Videos
- Publication text
- Photos
- Videos
- Publication text
- Photos
- Videos
- Content delivery without opening Facebook
- Videos
- Photos
- GIFs
- Galleries
- Publication text
🧵 Threads
- Photos
- Videos
- Publication text
- Photos
- Videos
- Pin description
🦋 Bluesky
- Photos
- Videos
- Publication text
🎬 Vimeo
- Videos up to 10 minutes
🟣 Twitch Clips
- Twitch clips
- Videos up to 10 minutes
🖼 Imgur
- Photos
- Albums
- GIFs
- Videos
Overview
Hel_inst_bot is a unified content extraction layer placed between Telegram and multiple social networks. Instead of building a separate user workflow for every platform, the bot accepts a URL, determines its source, delegates extraction to the corresponding handler, and returns a normalized Telegram-ready result.
This normalization is important because every source behaves differently. Instagram may contain a carousel with mixed media, X and LinkedIn may combine publication text with attachments, YouTube requires duration and format checks, and Stories may depend on an authenticated session.
The bot hides these differences from the user. A person does not need to know whether a post is processed through yt-dlp, gallery-dl, Instaloader, a direct request, or an authenticated session. The public contract remains the same: send a link and receive viewable content.
The project is continuously maintained because social-media platforms frequently change markup, access rules, redirect behavior, authentication requirements, and downloadable formats. Its architecture therefore favors isolated handlers and replaceable extraction strategies instead of one tightly coupled parser.
What I Built
Core Features
- Automatic platform detection from incoming Telegram messages
- Independent handlers for thirteen social-media platforms.
- Support for videos, photos, carousels, Stories, Shorts, mixed posts, and text
- Telegram album delivery for multi-file publications
- Caption and text handling within Telegram message limitations
- Private-chat and group-administrator workflows
- Cookie-based authentication for restricted content flows
- Local statistics and administrator broadcast capabilities
- Windows scripts for starting, stopping, and restarting the bot
Responsibilities
- Designed the Telegram interaction and routing layer
- Implemented and maintained platform-specific media handlers
- Integrated multiple extraction libraries and fallback paths
- Added support for new content types without breaking existing flows
- Handled Telegram media-group, file-size, caption, and text constraints
- Built cookie conversion and authenticated-session workflows
- Created local process-management scripts for reliable daily operation
- Documented setup, environment configuration, cookies, and administration
Technical Details
Incoming messages are first classified by URL pattern. The router selects a platform handler and passes it the source link together with the Telegram chat context. Each handler is responsible for obtaining a normalized result: downloadable files, publication text, source metadata, and any platform-specific errors.
This design prevents Instagram-specific cookie logic or YouTube format selection from leaking into the Telegram layer. It also allows a single platform implementation to be fixed or replaced without destabilizing the rest of the bot.
Media extraction uses several tools because no single library handles every platform and publication type reliably. yt-dlp is suitable for many video sources, gallery-dl helps with image collections and carousels, Instaloader supports Instagram-specific authenticated flows, and direct requests are used where a simpler path is more stable.
Cookies are treated as an operational adapter rather than hard-coded application state. Browser-exported cookies can be converted into the Netscape format expected by command-line downloaders. This is especially important for Instagram, where anonymous requests, account restrictions, and session requirements can change over time.
Telegram delivery has its own constraints. A publication may contain more files than fit comfortably in one response, captions have length limits, and text posts need to remain readable even when attachments are present. The delivery layer therefore separates media grouping from text sending and chooses the appropriate Telegram method for each normalized result.
The bot also includes local operational tooling for Windows. Start, stop, and restart scripts make it possible to recover the service without manually finding processes, while the VBS launcher allows background startup without leaving a terminal window open.
Challenges & Solutions
-
Challenge: Every social network exposes media differently and changes behavior independently.
Solution: Isolated each platform in a dedicated handler with a shared normalized output contract.
Result: Platform-specific fixes can be released without rewriting the Telegram workflow. -
Challenge: Instagram publications include photos, videos, mixed carousels, Reels, and Stories with different access requirements.
Solution: Combined multiple extraction strategies and authenticated cookie/session support.
Result: One user action can retrieve a much wider range of Instagram content types. -
Challenge: Browser cookies and downloader cookies use incompatible formats.
Solution: Added conversion from exported JSON cookies to Netscape cookie files.
Result: Session refresh became a repeatable maintenance operation instead of a manual rewrite. -
Challenge: Telegram has separate rules for files, albums, captions, and long publication text.
Solution: Built a delivery layer that chooses between single media, media groups, captions, and follow-up text messages.
Result: Complex posts remain readable and forwardable inside Telegram. -
Challenge: A bot used in active groups must not require every member to open a private chat first.
Solution: Added group-administrator mode with link detection directly in group messages.
Result: The bot becomes part of the conversation rather than a separate utility. -
Challenge: Local background processes can remain active after code updates and block a clean restart.
Solution: Added dedicated start, stop, restart, and hidden-launch scripts.
Result: Updating and recovering the bot became predictable on Windows.
Development Evolution
The project grew from an Instagram-focused utility into a multi-platform Telegram media service. Each stage expanded either the supported content surface or the reliability of daily operation.
Stage 1 — Instagram Utility
- Direct Instagram link processing
- Photo and video delivery
- Basic Telegram interaction
Stage 2 — Complex Instagram Content
- Carousels and mixed posts
- Reels and Stories
- Session and cookie support
Stage 3 — Multi-Platform Expansion
- TikTok and Facebook handlers
- X media and post text
- Platform detection and routing
Stage 4 — YouTube & LinkedIn
- YouTube videos and Shorts
- Ten-minute duration guard
- LinkedIn media and publication text
Stage 5 — Operations
- Start, stop, and restart scripts
- Background launch on Windows
- Cookie conversion workflow
Stage 6 — Product Administration
- User and group statistics
- Administrator broadcast
- Updated setup and maintenance documentation
- Added Reddit support
- Added Threads support
- Added Pinterest support
- Added Bluesky support
- Added Vimeo support
- Added Twitch Clips support
- Added Imgur support
Result
Hel_inst_bot evolved from a single-platform downloader into a unified Telegram content gateway for six social networks.
Users can now share photos, videos, carousels, Stories, Shorts, and post text without interrupting the conversation or requiring every participant to have access to the original platform.
From an engineering perspective, the project demonstrates practical integration work under unstable external conditions: multiple parsers, authenticated sessions, platform-specific fallbacks, Telegram API limitations, content normalization, and local service operations.
Try Hel_inst_bot
Send a supported social-media link in a private conversation, or add the bot as an administrator to a Telegram group and use links directly inside the chat.
No separate application is required — the entire workflow stays inside Telegram.