X.com (Twitter) Image Bot 🤖

A Python bot that automatically posts images from your upload_images folder to X.com (Twitter) with custom titles on a schedule.

Features ✨

• 📷 Bulk Image Posting: Handles 20-30+ images automatically
• ⏰ Scheduled Posting: Posts on your specified schedule
• 📝 Custom Titles: Configurable post titles with rotation
• 📁 File Management: Automatically moves posted images to posted_images folder
• 🔧 Easy Configuration: JSON-based settings
• 🛡️ Error Handling: Robust error handling and logging

Quick Setup 🚀

1. Get Twitter API Credentials

1. Go to Twitter Developer Portal
2. Create a new app
3. Get your API credentials:
   • API Key (Consumer Key)
   • API Secret (Consumer Secret)
   • Access Token
   • Access Token Secret
   • Bearer Token

2. Configure the Bot

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and add your Twitter API credentials:

   TWITTER_API_KEY=your_api_key_here
   TWITTER_API_SECRET=your_api_secret_here
   TWITTER_ACCESS_TOKEN=your_access_token_here
   TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret_here
   TWITTER_BEARER_TOKEN=your_bearer_token_here

3. Add Your Images

Put your images in the upload_images folder:

# Supported formats: .jpg, .jpeg, .png, .gif
cp your_images/* upload_images/

Usage 📱

Test the Bot

python run_bot.py test

Post Images Immediately

python run_bot.py post-now

Start Scheduled Posting

python run_bot.py schedule

Update Custom Titles

python run_bot.py update-titles

Configuration ⚙️

Edit config.json to customize:

{
  "custom_titles": [
    "Check out this amazing shot! 📸",
    "New post! What do you think? 🤔",
    "Sharing some visual inspiration ✨"
  ],
  "posting_schedule": {
    "enabled": true,
    "time": "09:00",
    "timezone": "UTC",
    "use_interval": false,
    "interval_minutes": 30
  },
  "settings": {
    "max_images_per_run": 25,
    "image_formats": [".jpg", ".jpeg", ".png", ".gif"],
    "shuffle_titles": true
  }
}

Configuration Options

• custom_titles: Array of titles to use for posts
• posting_schedule:
  • time: Daily posting time (24-hour format)
  • timezone: Timezone for scheduled posting (Unix/Linux only - Windows uses local time)
  • use_interval: Use interval-based posting instead of daily time
  • interval_minutes: How often to check for new images (when use_interval is true)
• settings:
  • max_images_per_run: How many images to post per cycle (default: 25 for bulk posting)
  • shuffle_titles: Randomize titles or use in order

How It Works 🔄

1. Image Detection: Bot scans upload_images folder for supported image formats
2. Posting: Posts images with custom titles to Twitter
3. File Management: Moves posted images to posted_images with timestamps
4. Scheduling: Continues running on your specified schedule

File Structure 📁

├── upload_images/          # Put your images here
├── posted_images/          # Posted images moved here automatically
├── config.json            # Bot configuration
├── twitter_bot.py         # Main bot script
├── run_bot.py             # Easy runner script
├── .env                   # Your API credentials (create from .env.example)
└── .env.example           # Environment template

Troubleshooting 🔧

Common Issues

"No images found"

• Make sure images are in upload_images folder
• Check supported formats: .jpg, .jpeg, .png, .gif

"Twitter API error"

• Verify your API credentials in .env
• Check your Twitter app permissions (needs read/write access)

"Image too large"

• Twitter limit is 5MB per image
• Bot will skip oversized images and continue

Getting Help

1. Run python run_bot.py test to check setup
2. Check the console output for detailed error messages
3. Verify your Twitter API credentials and app permissions

Safety Features 🛡️

• Rate Limiting: Built-in delays to respect Twitter API limits
• Image Validation: Checks image format and size before posting
• Error Recovery: Continues processing other images if one fails
• Backup: Original images moved to posted_images, not deleted

Tips 💡

• Start with a few test images first
• Use descriptive custom titles for better engagement
• Monitor the bot's console output for any issues
• Keep your API credentials secure and never share them

Happy posting! 🎉