Telegram Instagram Bot

A specialized Telegram bot designed to work in multiple group chats and the owner's personal chat with these features:

1. Instagram Video Downloader: Automatically downloads and reposts Instagram reels and videos when links are shared
2. Ukrainian Keyword Response: Responds with a custom GIF when a specific user sends messages containing configurable trigger words

Features

• 🎬 Instagram Video Support: Silently downloads and sends videos from Instagram posts (images are skipped)
• 🇺🇦 Ukrainian Keyword Detection: Silently responds with GIF to configurable trigger words
• ⚡ Rate Limiting: Limits GIF target users to 5 Instagram requests per minute (silently sends GIF if exceeded)
• 💾 Smart Caching: Rate-limited users get cached videos for repeated URLs (reduces Instagram API calls)
• 🏠 Multi-Chat Operation: Works in multiple groups + owner's personal chat
• 👤 Owner-Only Configuration: Only the bot owner can access configuration commands
• 📁 Automatic Cleanup: Downloads are automatically deleted after posting
• 📝 Comprehensive Logging: Full logging of all operations

Setup Instructions

1. Prerequisites

• Python 3.8 or higher
• A Telegram account
• Instagram video content you want to download (public posts)

2. Create a Telegram Bot

1. Message @BotFather on Telegram
2. Send /newbot and follow the instructions
3. Save the bot token you receive

3. Get Required IDs

You'll need these Telegram IDs:

• Your User ID: Message @userinfobot to get your ID (enables personal chat)
• Group Chat IDs: Add the bot to your groups, then use /config to see chat IDs
• Target User ID: Get the ID of the person who should trigger GIF responses

💡 The bot automatically works in:

• ✅ Your personal chat (using your user ID)
• ✅ All groups you specify in TARGET_GROUPS

4. Installation

1. Clone or download this repository

2. Install dependencies:

   pip install -r requirements.txt

3. Create environment configuration:

   cp env_example.txt .env

4. Edit .env file with your values:

   TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
   OWNER_USER_ID=your_telegram_user_id
   TARGET_GROUPS=-4868143256,-1234567890,-9876543210
   RATE_LIMITED_USERS=324187121,987654321,555666777
   GIF_FILE_PATH=path_to_your_gif_file.gif

   Multiple Groups: Use comma-separated list of group IDs Multiple Rate-Limited Users: Use comma-separated list of user IDs for rate limiting, caching, and GIF responses Single Group/User: You can still use TARGET_GROUP_ID and GIF_TARGET_USER_ID for backward compatibility

5. Add your GIF file:

   • Place your GIF file in the project directory
   • Update GIF_FILE_PATH in .env to point to your GIF

6. Setup Instagram Authentication (Optional but Recommended):

   Instagram downloads may fail without proper authentication. Set up cookies for reliable access:

   Method 1 - Browser Cookie Extraction (Easy):

   # In your .env file, set to your browser name (NATIVE ENVIRONMENTS ONLY)
   INSTAGRAM_BROWSER=chrome  # or firefox, safari, edge

   Method 2 - Manual Cookie File (WSL/Fallback):

   # Leave browser empty and provide cookie file
   INSTAGRAM_BROWSER=
   INSTAGRAM_COOKIES_FILE=instagram_cookies.txt

   🐧 WSL Users: Browser extraction won't work. Use the helper script:

   python wsl_cookie_helper.py

   📖 For detailed setup instructions, see INSTAGRAM_COOKIES_SETUP.md

7. Run the Bot

python bot.py

Configuration

Environment Variables

Variable	Description	Required
TELEGRAM_BOT_TOKEN	Bot token from @BotFather	Yes
OWNER_USER_ID	Your Telegram user ID (also enables personal chat)	Yes
TARGET_GROUPS	Comma-separated list of group chat IDs where bot works	Yes*
TARGET_GROUP_ID	Single group chat ID (legacy - for backward compatibility)	Yes*
RATE_LIMITED_USERS	Comma-separated list of user IDs for rate limiting, caching, and GIF responses	Yes**
GIF_TARGET_USERS	DEPRECATED - Use RATE_LIMITED_USERS instead	No
GIF_TARGET_USER_ID	Single user ID (legacy - for backward compatibility)	Yes**
GIF_FILE_PATH	Path to GIF file	Yes
DOWNLOAD_DIR	Directory for temporary downloads	No (default: downloads)
TRIGGER_WORDS	Trigger words for GIF (comma-separated)	No (default: бот,ботанік,ботик)
LOG_LEVEL	Logging level	No (default: INFO)
LOG_FILE	Log file path	No (default: bot.log)
INSTAGRAM_BROWSER	Browser name for cookie extraction (chrome/firefox/safari/edge)	No
INSTAGRAM_USERNAME	DEPRECATED - Use INSTAGRAM_BROWSER instead	No
INSTAGRAM_COOKIES_FILE	Manual Instagram cookies file path	No (default: instagram_cookies.txt)
CACHE_ENABLED	Enable video caching for rate-limited users	No (default: true)
CACHE_DIR	Directory for cached videos	No (default: cache)
CACHE_MAX_AGE_DAYS	Keep cached files for X days	No (default: 7)
CACHE_MAX_SIZE_MB	Maximum cache size in MB	No (default: 500)

* Either TARGET_GROUPS or TARGET_GROUP_ID is required (not both). Use TARGET_GROUPS for multiple groups, or TARGET_GROUP_ID for a single group (legacy).

** Either RATE_LIMITED_USERS or GIF_TARGET_USER_ID is required (not both). Use RATE_LIMITED_USERS for multiple users, or GIF_TARGET_USER_ID for a single user (legacy).

Usage

Commands (Owner Only)

• /start - Show bot information
• /status - Check bot status and statistics
• /config - Show current configuration

Automatic Features

1. Instagram Videos:

   • Just share any Instagram reel/post link in the group
   • Bot silently downloads and sends video content (no status messages)
   • Videos: Reels, IGTV, regular videos
   • Note: Image-only posts are silently skipped
   • Limitation: Only works with public posts or posts accessible without login

2. Ukrainian Response:

   • When configured users send messages containing trigger words
   • Default trigger words: "бот", "ботанік", "ботик" (configurable)
   • Supports exact matches and words starting with trigger words
   • Bot silently replies with the configured GIF

3. Rate Limiting:

   • Who: Only applies to users configured in RATE_LIMITED_USERS
   • Limit: Maximum 5 Instagram download requests per minute (per user)
   • Counting: Each Instagram URL counts as one request (even if multiple URLs in one message)
   • Behavior: If limit exceeded, bot silently sends GIF and stops processing remaining URLs
   • Reset: Rate limit automatically resets after 1 minute
   • Purpose: Prevents spam and reduces Instagram API usage

4. Smart Caching:

   • Who: Only applies to rate-limited users (configured in RATE_LIMITED_USERS)
   • Purpose: If rate-limited users spam the same Instagram URLs repeatedly, videos are served from local cache
   • Benefits: Faster responses, reduced Instagram API calls, bandwidth savings
   • Cache Key: Based on Instagram URL (same URL = same cached video)
   • Storage: Videos stored in cache/ directory with automatic cleanup
   • Limits:
     • Age: Files older than 7 days are automatically deleted
     • Size: Cache limited to 500MB total (oldest files removed first)
   • Behavior: Cache hit = instant video send, Cache miss = download and cache for future
   • Configuration: Can be disabled by setting CACHE_ENABLED=false in .env

Supported Instagram Content

📱 URL Formats

• instagram.com/reel/... - Video reels
• instagram.com/p/... - Posts (only videos will be downloaded)
• instagram.com/tv/... - IGTV videos
• instagr.am/reel/... - Short reel URLs
• instagr.am/p/... - Short post URLs

🎬 Content Types

• ✅ Video reels - Instagram reels and short videos
• ✅ Regular videos - Longer video posts
• ✅ IGTV videos - Instagram TV content
• ❌ Photos/Images - Will be skipped (not downloaded)
• ❌ Photo carousels - Will be skipped (not downloaded)
• ❌ Mixed content - Only video parts will be downloaded

Security Features

• Only works in the specified group chat
• Configuration commands are owner-only
• No data is stored permanently (downloads are cleaned up)
• Comprehensive logging for monitoring

Troubleshooting

🧪 Testing Your Setup

First, run the test script to verify your configuration:

python test_bot.py

This will test:

• Configuration validity
• Instagram URL detection
• Ukrainian keyword matching
• File operations

Common Issues

1. Bot not responding:

   • Check if bot is added to the correct groups
   • Verify TARGET_GROUPS contains correct chat IDs (use python get_chat_id.py)
   • Check bot has necessary permissions in the groups
   • Owner can also message bot directly in personal chat
   • Look at bot.log for detailed error messages

2. Instagram video downloads failing:

   • Setup cookies first: See INSTAGRAM_COOKIES_SETUP.md for detailed instructions
   • Bot only downloads videos - image posts will be skipped
   • Check if post contains video content (not just images)
   • Authentication errors: "Login required" means cookies are needed or expired
   • Rate limiting: Instagram may block downloads - wait 15-30 minutes or setup cookies
   • Update yt-dlp: pip install --upgrade yt-dlp
   • Private or restricted posts may not work even with cookies

3. GIF not sending:

   • Verify GIF_FILE_PATH points to a valid file
   • Check file permissions and format (GIF, MP4, etc.)
   • Ensure file size is under Telegram limits (50MB)
   • Make sure the message is from the correct user ID
   • Test with python test_bot.py to verify keyword detection

4. Ukrainian keyword not working:

   • Check your TRIGGER_WORDS configuration (comma-separated list)
   • Message must be from users specified in RATE_LIMITED_USERS
   • Words must match or start with any of your configured trigger words
   • Default trigger words: "бот", "ботанік", "ботик"
   • Example: "hello бот" will trigger if "бот" is in your trigger words list
   • Check bot.log for detailed debugging info

5. Rate limiting questions:

   • Only users in RATE_LIMITED_USERS are rate limited for Instagram downloads
   • Other users can still download without limits
   • Rate limit is 5 Instagram requests per minute (60 seconds per user)
   • Each Instagram URL counts as one request (5 URLs in one message = 5 requests)
   • When exceeded, GIF is silently sent and remaining URLs are skipped
   • No user-visible messages - check bot.log for rate limit events: "Rate limit exceeded"
   • Use /config command to see current rate limit settings

Getting Group Chat ID and User IDs

Method 1: Standard ID Finder

python get_chat_id.py

1. Add your bot to the group (temporarily)
2. Send a message - you'll see:
   • Group chat ID
   • All administrators with IDs
   • Your user ID
3. To get other user IDs: Ask group members to send any message while the script runs
4. All active users will be tracked and shown with their IDs

Method 2: Main Bot Config

Use /config command with your main bot if you're the owner

Logs

Check bot.log for detailed information about bot operations, errors, and debugging information.

File Structure

bot2/
├── bot.py              # Main bot script
├── config.py           # Configuration management
├── get_chat_id.py      # Utility to find chat and user IDs
├── test_bot.py         # Test script for debugging
├── setup.py            # Automated setup script
├── wsl_cookie_helper.py # WSL cookie setup helper
├── requirements.txt    # Python dependencies
├── env_example.txt     # Environment variables example
├── README.md          # This file
├── FIX_BOT_PERMISSIONS.md # Bot permission troubleshooting guide
├── INSTAGRAM_COOKIES_SETUP.md # Instagram cookie authentication guide
├── downloads/         # Temporary download directory (created automatically)
├── bot.log           # Log file (created automatically)
└── your_gif.gif      # Your GIF file for responses

Dependencies

• python-telegram-bot - Telegram Bot API wrapper
• yt-dlp - Instagram video downloader (videos only)
• pathlib - Path handling
• asyncio - Asynchronous operations

Notes

• The bot automatically creates a downloads folder for temporary files
• All downloaded Instagram content is deleted after posting to save space
• Videos Only: The bot will skip Instagram posts that contain only images
• The bot responds to configurable trigger words (default: "бот", "ботанік", "ботик")
• Cookie Authentication: Use browser cookies for reliable Instagram downloads
• Make sure your GIF file is accessible and not too large (Telegram has size limits)

Support

If you encounter issues:

1. Check the logs in bot.log
2. Verify all configuration values are correct
3. Ensure the bot has proper permissions in the group
4. Set up Instagram cookie authentication using INSTAGRAM_COOKIES_SETUP.md
5. Check that all required files exist and are accessible