botusun/tweetbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

init

Browse Source
This commit is contained in:
Botu SUN
2025-10-24 20:38:44 +09:00
commit 1a1b8b9077
10 changed files with 1324 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

432
README.md Normal file
View File

@@ -0,0 +1,432 @@
# TweetBot - AI-Powered Twitter Bot
An automated Twitter bot that generates and posts tweets using OpenAI's ChatGPT API. This Java application allows you to create engaging social media content with custom prompts.
## Features
- Generate tweet content using ChatGPT (GPT-3.5-turbo)
- **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
- OpenAI API key
- Twitter Developer Account with API credentials
## Setup Instructions
### 1. Get OpenAI API Key
1. Go to [OpenAI Platform](https://platform.openai.com/)
2. Sign up or log in to your account
3. Navigate to API keys section
4. Create a new API key and save it securely
### 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
- Bearer Token
**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:
```
OPENAI_API_KEY=sk-your-openai-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
TWITTER_BEARER_TOKEN=your-twitter-bearer-token
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)
### 5. 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/
│ ├── OpenAIService.java # ChatGPT integration
│ └── TwitterService.java # Twitter API integration
└── resources/
└── logback.xml # Logging configuration
```
## Configuration Options
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `OPENAI_API_KEY` | Yes | Your OpenAI API key |
| `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 |
| `TWITTER_BEARER_TOKEN` | Yes | Twitter Bearer Token |
| `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 OpenAI API key is valid
2. Check that you have sufficient API credits
3. Review the error message in logs
### 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
- **Twitter API Java SDK** (2.0.3) - Twitter API client
- **OpenAI GPT-3 Java** (0.18.2) - OpenAI API client
- **OkHttp** (4.12.0) - HTTP client
- **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
- Add support for images and media attachments
- 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 OpenAI API status pages