# 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.0-flash-exp) - **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](https://aistudio.google.com/app/apikey)
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 Google Gemini includes:
- 15 requests per minute
- 1 million tokens per minute
- 1,500 requests per day
- More than enough for a tweet bot!

### 2. Get Twitter API Credentials

1. Go to [Twitter Developer Portal](https://developer.twitter.com/en/portal/dashboard)
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"

### 3. Configure the Application

1. Copy the example environment file:
   ```bash
   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

```bash
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:

```bash
java -jar target/tweetbot-1.0.0.jar
```

Or using Maven:

```bash
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:

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

Or with a custom prompt:

```bash
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:

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

With custom prompt:

```bash
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:

```bash
# 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`:
   ```bash
   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:

```bash
# 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`:

```ini
[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:

```bash
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

### "Failed to generate tweet"

1. Verify your Gemini API key is valid
2. Check that you're within the free tier rate limits (15 RPM, 1500 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`:

```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