tweetbot/README.md

TweetBot - AI-Powered Twitter Bot

An automated Twitter bot that generates and posts tweets using Google Gemini's free API. This Java application allows you to create engaging social media content with custom prompts.

Features

• Generate tweet content using Google Gemini (gemini-2.5-flash) - Free Tier
• Three operation modes:
  • Interactive mode with manual approval
  • Auto-post mode for one-time tweets
  • Scheduled mode (posts every 30 minutes)
• Attach images to tweets - Include a static image from local file system with every tweet
• Automatic tweet posting at regular intervals
• Customizable prompts for different content types
• Character limit validation (280 characters)
• Graceful error handling with automatic retry
• Comprehensive logging (console and file)
• Environment-based configuration
• Background service support

Prerequisites

• Java 17 or higher
• Maven 3.6 or higher
• Google Gemini API key (free tier available)
• Twitter Developer Account with API credentials

Setup Instructions

1. Get Google Gemini API Key (Free)

1. Go to Google AI Studio
2. Sign in with your Google account
3. Click "Create API Key"
4. Select or create a Google Cloud project
5. Copy the API key and save it securely

Note: The free tier of Gemini 2.5 Flash includes:

• 10 requests per minute
• 250,000 tokens per minute
• 250 requests per day
• More than enough for a tweet bot!

2. Get Twitter API Credentials

1. Go to Twitter Developer Portal
2. Create a new project and app (or use existing)
3. Navigate to your app's "Keys and tokens" section
4. Generate and save the following credentials:
   • API Key (Consumer Key)
   • API Secret (Consumer Secret)
   • Access Token
   • Access Token Secret

Important: Ensure your Twitter app has Read and Write permissions:

• Go to your app settings
• Navigate to "User authentication settings"
• Set app permissions to "Read and Write"

Note: This application uses Twitter API v2 for posting tweets (compatible with Free and Basic access tiers) and v1.1 for media uploads.

3. Configure the Application

1. Copy the example environment file:

   cp .env.example .env
   

2. Edit .env and add your API credentials:

   GEMINI_API_KEY=your-gemini-api-key-here
   TWITTER_API_KEY=your-twitter-api-key
   TWITTER_API_SECRET=your-twitter-api-secret
   TWITTER_ACCESS_TOKEN=your-twitter-access-token
   TWITTER_ACCESS_TOKEN_SECRET=your-twitter-access-token-secret
   TWEET_PROMPT=Write a short, engaging tweet about technology trends
   IMAGE_PATH=/path/to/your/image.jpg
   

3. Customize the TWEET_PROMPT to match your desired content theme

4. (Optional) Configure Image Attachment:

   • Set IMAGE_PATH to the absolute path of an image file (jpg, png, gif)
   • This image will be attached to every tweet
   • Leave empty or comment out to post text-only tweets
   • Example: IMAGE_PATH=/home/user/images/logo.png
   • Supported formats: JPEG, PNG, GIF
   • Maximum file size: 5MB (Twitter limit)

4. Build the Project

mvn clean package

This will:

• Download all dependencies
• Compile the source code
• Run tests (if any)
• Create an executable JAR file in the target directory

Usage

TweetBot supports three modes of operation:

1. Interactive Mode (Default)

Generate a tweet and manually approve before posting:

java -jar target/tweetbot-1.0.0.jar

Or using Maven:

mvn exec:java -Dexec.mainClass="com.voidcode.tweetbot.TweetBot"

2. Scheduled Mode (Auto-post every 30 minutes)

Run continuously and automatically post tweets every 30 minutes:

java -jar target/tweetbot-1.0.0.jar --schedule

Or with a custom prompt:

java -jar target/tweetbot-1.0.0.jar --schedule "Write daily tech tips"

The bot will:

• Post immediately when started
• Post a new tweet every 30 minutes
• Run continuously until stopped with Ctrl+C
• Automatically recover from errors and retry at the next interval

Note: In scheduled mode, tweets are posted automatically without manual confirmation.

3. Auto-Post Mode (One-time)

Generate and post a single tweet automatically without confirmation:

java -jar target/tweetbot-1.0.0.jar --auto

With custom prompt:

java -jar target/tweetbot-1.0.0.jar --auto "Write a motivational quote about perseverance"

Command-Line Options

Option	Short	Description
--schedule	-s	Run in scheduled mode (posts every 30 minutes)
--auto	-a	Auto-post without confirmation (one-time)
--help	-h	Show help message

Example Output

Interactive Mode:

==========================================================
Generated Tweet:
==========================================================
The future of AI is not about replacing humans, but
augmenting our capabilities. Together, we can achieve
what neither could alone.
==========================================================
Character count: 145/280
==========================================================

Do you want to post this tweet? (yes/no): yes

==========================================================
SUCCESS! Tweet posted successfully!
Tweet ID: 1234567890123456789
View at: https://twitter.com/user/status/1234567890123456789
==========================================================

Scheduled Mode:

==========================================================
TweetBot - SCHEDULED MODE
==========================================================
Tweet will be posted every 30 minutes
Press Ctrl+C to stop
==========================================================

==========================================================
[2025-10-24 14:30:00] Tweet Posted Successfully!
==========================================================
AI is transforming how we work, learn, and create.
The future is collaborative intelligence.
==========================================================
Tweet ID: 1234567890123456789
View at: https://twitter.com/user/status/1234567890123456789
Next tweet in 30 minutes
==========================================================

Project Structure

tweetbot/
├── pom.xml                          # Maven configuration
├── .env                             # Environment variables (not in git)
├── .env.example                     # Example environment file
├── README.md                        # This file
└── src/
    └── main/
        ├── java/
        │   └── com/
        │       └── voidcode/
        │           └── tweetbot/
        │               ├── TweetBot.java              # Main application
        │               ├── config/
        │               │   └── Config.java            # Configuration loader
        │               └── service/
        │                   ├── GeminiService.java     # Google Gemini integration
        │                   └── TwitterService.java    # Twitter API integration
        └── resources/
            └── logback.xml          # Logging configuration

Configuration Options

Environment Variables

Variable	Required	Description
GEMINI_API_KEY	Yes	Your Google Gemini API key (free tier available)
TWITTER_API_KEY	Yes	Twitter API Key (Consumer Key)
TWITTER_API_SECRET	Yes	Twitter API Secret (Consumer Secret)
TWITTER_ACCESS_TOKEN	Yes	Twitter Access Token
TWITTER_ACCESS_TOKEN_SECRET	Yes	Twitter Access Token Secret
TWEET_PROMPT	No	Default prompt for tweet generation
IMAGE_PATH	No	Path to image file to attach to every tweet (jpg, png, gif)

Customizing Tweet Generation

You can customize the tweet generation by modifying the prompt. Here are some examples:

# Technology news (interactive mode)
java -jar target/tweetbot-1.0.0.jar "Write a tweet about the latest AI breakthrough"

# Motivational content (auto-post)
java -jar target/tweetbot-1.0.0.jar --auto "Write an inspiring quote about success"

# Product updates (scheduled)
java -jar target/tweetbot-1.0.0.jar --schedule "Announce a new feature for a productivity app"

# Educational content (scheduled)
java -jar target/tweetbot-1.0.0.jar --schedule "Share an interesting fact about space exploration"

Attaching Images to Tweets

Every tweet can include a static image from your local file system:

Setup:

1. Place your image file anywhere on your system
2. Add the absolute path to .env:

   IMAGE_PATH=/home/user/images/brand-logo.png
   

3. Run the bot normally - the image will be automatically attached to every tweet

Image Requirements:

• Supported formats: JPEG (.jpg, .jpeg), PNG (.png), GIF (.gif)
• Maximum file size: 5MB (Twitter API limit)
• Recommended dimensions: 1200x675 pixels for optimal display
• The image must exist at the specified path when the bot runs

Example Use Cases:

• Brand logo or watermark on every tweet
• Product image for promotional content
• Infographic or visual content
• Profile or avatar image

To disable images:

• Comment out or remove the IMAGE_PATH line in .env
• Or set it to an empty value: IMAGE_PATH=

Note: If the image file is not found or fails to upload, the tweet will still be posted without the image, and an error will be logged.

Running as a Background Service

To run the bot continuously in the background on Linux/Mac:

# Run in background
nohup java -jar target/tweetbot-1.0.0.jar --schedule > tweetbot.out 2>&1 &

# Check if it's running
ps aux | grep tweetbot

# View output
tail -f tweetbot.out

# Stop the bot
pkill -f tweetbot

Using systemd (Linux):

Create a service file /etc/systemd/system/tweetbot.service:

[Unit]
Description=TweetBot - Automated Twitter Posting
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/tweetbot
ExecStart=/usr/bin/java -jar /path/to/tweetbot/target/tweetbot-1.0.0.jar --schedule
Restart=always
RestartSec=60
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Then enable and start:

sudo systemctl daemon-reload
sudo systemctl enable tweetbot
sudo systemctl start tweetbot
sudo systemctl status tweetbot

# View logs
sudo journalctl -u tweetbot -f

Logging

The application creates logs in two places:

• Console output: Real-time logs with timestamps
• File output: tweetbot.log in the project directory

Log levels:

• INFO: General application flow
• WARN: Warnings and non-critical issues
• ERROR: Errors and exceptions

Security Best Practices

1. Never commit .env file - It contains sensitive API keys
2. Use environment variables - For production deployments
3. Rotate API keys regularly - Update keys periodically
4. Limit API permissions - Only grant necessary permissions
5. Monitor API usage - Check for unusual activity

Troubleshooting

"Missing required environment variable"

Ensure your .env file exists and contains all required variables.

"Failed to verify Twitter credentials"

1. Check that your API keys are correct
2. Verify your app has Read and Write permissions
3. Regenerate access tokens if needed

"You currently have access to a subset of X API V2 endpoints" (403 error code 453)

This error means your Twitter API access level doesn't support v1.1 tweet posting. The code has been updated to use API v2 which is supported by all access tiers (Free, Basic, Pro). Make sure you're using the latest version of the code.

"Failed to generate tweet"

1. Verify your Gemini API key is valid
2. Check that you're within the free tier rate limits (10 RPM, 250 RPD)
3. Review the error message in logs
4. Ensure your Google Cloud project is properly configured

Twitter API Rate Limits

Twitter API has rate limits:

• Tweet creation: 300 tweets per 3 hours (100 per hour average)
• The default 30-minute interval allows for 6 tweets per 3 hours, well within limits
• Monitor your usage to avoid hitting limits
• If you modify the schedule interval, ensure you stay within rate limits

Dependencies

• OkHttp (4.12.0) - HTTP client for API requests
• Jackson (2.16.1) - JSON processing
• SLF4J & Logback (2.0.9) - Logging
• Dotenv (3.0.0) - Environment variable management

Contributing

Feel free to fork this project and customize it for your needs. Some ideas:

Customizing the Schedule Interval

To change the posting frequency from 30 minutes to another interval, edit TweetBot.java:

private static final int SCHEDULE_INTERVAL_MINUTES = 30; // Change this value

Other Enhancement Ideas

• Implement tweet threading for longer content
• Add sentiment analysis before posting
• Create multiple prompt templates with rotation
• Store tweet history in a database
• Add analytics and engagement tracking
• Support for multiple Twitter accounts
• Implement tweet approval queue/review system

License

This project is open source and available for educational purposes.

Disclaimer

Use this bot responsibly and in accordance with Twitter's Terms of Service and Automation Rules. Ensure you comply with rate limits and don't spam or post misleading content.

Support

For issues or questions:

1. Check the troubleshooting section
2. Review application logs in tweetbot.log
3. Verify API credentials and permissions
4. Check Twitter and Google AI Studio status pages