commit 87ca24ea46350b482ad3ff0b77584adee95eb915 Author: andri Date: Tue Sep 23 19:32:39 2025 +0000 Add README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..dc12522 --- /dev/null +++ b/README.md @@ -0,0 +1,337 @@ +# WhatsApp Hybrid Gateway + +A production-ready WhatsApp integration solution that combines a powerful REST API gateway with an intelligent interactive bot. Built with the Baileys library for reliable WhatsApp Web connectivity. + +## Features + +### 🚀 Dual Functionality +- **REST API Gateway**: Full-featured API for external applications +- **Interactive Bot**: Smart auto-response bot for direct WhatsApp users +- **Shared Connection**: Single WhatsApp connection serves both functions + +### 📱 Complete Media Support +- Text messages with rich formatting +- Images with captions (JPG, PNG, GIF, WebP) +- Documents (PDF, DOC, XLS, PPT, TXT, ZIP) +- Audio files and voice notes (MP3, WAV, OGG, M4A) +- Videos with captions (MP4, AVI, MOV, MKV, WebM) +- Stickers (WebP format) + +### 🛡️ Production Ready +- Environment-based configuration +- Systemd service integration +- Comprehensive logging system +- Error handling and retry mechanisms +- File upload validation and security +- Graceful shutdown handling + +### 🤖 Interactive Bot Features +- Auto-response to media (image → image, audio → audio) +- Command system (`/help`, `/multimedia`, `/foto`, etc.) +- Dynamic content generation (memes, quotes, reports) +- Smart conversation handling + +### 🔧 API Gateway Features +- RESTful endpoints for all media types +- Consistent JSON response format +- Optional API key authentication +- File upload with automatic cleanup +- Detailed error responses +- Rate limiting support + +## Quick Start + +### Prerequisites +- Node.js 16+ and npm +- Ubuntu/Linux server (recommended) +- WhatsApp account for QR scanning + +### Installation + +1. **Clone the repository** +```bash +git clone https://git.classy.id/andri/whatsapp-hybrid-gateway.git +cd whatsapp-hybrid-gateway +``` + +2. **Install dependencies** +```bash +npm install +``` + +3. **Configure environment** +```bash +cp .env.example .env +nano .env +``` + +4. **Start the application** +```bash +# Development +npm start + +# Production with PM2 +npm run prod +``` + +5. **Scan QR Code** +- QR code will appear in terminal +- Scan with WhatsApp on your phone +- Wait for "System Ready" message + +## Configuration + +Create `.env` file with your settings: + +```env +# Server Configuration +NODE_ENV=production +PORT=5000 +HOST=0.0.0.0 + +# Features Control +ENABLE_API=true +ENABLE_INTERACTIVE_BOT=true + +# WhatsApp Bot +BOT_NAME=WhatsApp Hybrid Gateway +SESSION_DIR=./session +UPLOADS_DIR=./uploads +LOGS_DIR=./logs +MEDIA_DIR=./media + +# Security (optional) +API_KEY=your-secret-api-key + +# Logging +LOG_LEVEL=info +LOG_TO_FILE=true +``` + +## API Documentation + +### Health Check +```bash +GET / +``` + +### Send Text Message +```bash +curl -X POST http://localhost:5000/api/send-message \ + -H "Content-Type: application/json" \ + -d '{"phone":"6281234567890","message":"Hello World!"}' +``` + +### Send Image +```bash +curl -X POST http://localhost:5000/api/send-image \ + -F "phone=6281234567890" \ + -F "caption=Sample image" \ + -F "file=@image.jpg" +``` + +### Other Endpoints +- `POST /api/send-document` - Send documents +- `POST /api/send-audio` - Send audio files +- `POST /api/send-video` - Send videos +- `POST /api/send-sticker` - Send stickers +- `GET /api/status` - Check bot status + +For complete API documentation, see [API_DOCUMENTATION.md](./API_DOCUMENTATION.md) + +## Interactive Bot Commands + +Send these commands directly to your WhatsApp bot: + +- `/help` - Show available commands +- `/multimedia` - Multimedia features menu +- `/foto` - Get a sample image +- `/audio` - Get a sample audio +- `/dokumen` - Get a system report +- `/sticker` - Get a sample sticker +- `/video` - Get a sample video +- `/meme` - Random meme generator +- `/quote` - Inspirational quote with image +- `/info` - System information + +## Deployment + +### Systemd Service (Ubuntu/Linux) + +1. **Create service file** +```bash +sudo nano /etc/systemd/system/whatsapp-gateway.service +``` + +2. **Service configuration** +```ini +[Unit] +Description=WhatsApp Hybrid Gateway +After=network.target + +[Service] +Type=simple +User=your-user +WorkingDirectory=/path/to/whatsapp-hybrid-gateway +ExecStart=/usr/bin/node app.js +Restart=always +RestartSec=5 +Environment=NODE_ENV=production +EnvironmentFile=/path/to/whatsapp-hybrid-gateway/.env + +[Install] +WantedBy=multi-user.target +``` + +3. **Enable and start** +```bash +sudo systemctl daemon-reload +sudo systemctl enable whatsapp-gateway +sudo systemctl start whatsapp-gateway +``` + +### PM2 Process Manager + +```bash +# Install PM2 +npm install -g pm2 + +# Start application +pm2 start app.js --name whatsapp-gateway + +# Save PM2 configuration +pm2 save +pm2 startup +``` + +## Project Structure + +``` +whatsapp-hybrid-gateway/ +├── app.js # Main application file +├── package.json # Dependencies and scripts +├── .env.example # Environment template +├── README.md # This file +├── API_DOCUMENTATION.md # Complete API docs +``` + +## Environment Variables + +| Variable | Description | Default | +|----------|-------------|---------| +| `NODE_ENV` | Environment mode | `development` | +| `PORT` | Server port | `5000` | +| `HOST` | Server host | `0.0.0.0` | +| `ENABLE_API` | Enable REST API | `true` | +| `ENABLE_INTERACTIVE_BOT` | Enable interactive bot | `true` | +| `BOT_NAME` | WhatsApp bot name | `WhatsApp Hybrid Gateway` | +| `API_KEY` | API authentication key | `null` | +| `LOG_LEVEL` | Logging level | `info` | +| `LOG_TO_FILE` | Enable file logging | `false` | + +## Testing + +```bash +# Run test suite +npm test + +# Test specific features +npm run test:api +npm run test:bot + +# Quick connectivity test +npm run test:quick +``` + +## Monitoring + +### Systemd Logs +```bash +# View real-time logs +sudo journalctl -u whatsapp-gateway -f + +# View recent logs +sudo journalctl -u whatsapp-gateway --since "1 hour ago" +``` + +### PM2 Monitoring +```bash +# Monitor processes +pm2 monit + +# View logs +pm2 logs whatsapp-gateway + +# Restart if needed +pm2 restart whatsapp-gateway +``` + +### Health Checks +```bash +# Check API status +curl http://localhost:5000/api/status + +# Check bot connection +curl http://localhost:5000/ | jq '.bot_connected' +``` + +## Troubleshooting + +### Common Issues + +**Bot not connecting:** +- Ensure QR code is scanned properly +- Check if session files are corrupted +- Verify network connectivity + +**API returns 503:** +- Bot may be disconnected +- Check systemd/PM2 logs +- Restart the service + +**File uploads failing:** +- Check file size limits +- Verify file type is supported +- Ensure sufficient disk space + +**Memory issues:** +- Monitor with `pm2 monit` +- Adjust max memory restart limits +- Check for memory leaks in logs + +### Log Files +- Application logs: `./logs/bot.log` +- PM2 logs: `~/.pm2/logs/` +- Systemd logs: `journalctl -u whatsapp-gateway` + +## Contributing + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +## Security Considerations + +- Use API keys in production environments +- Implement rate limiting for public APIs +- Regularly update dependencies +- Monitor for suspicious activity +- Use HTTPS in production +- Secure file upload directories + +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## Acknowledgments + +- [Baileys](https://github.com/adiwajshing/Baileys) - WhatsApp Web API library +- [Express.js](https://expressjs.com/) - Web framework +- [Multer](https://github.com/expressjs/multer) - File upload handling + + +--- + +**⚠️ Disclaimer:** This project is for educational and legitimate business use only. Ensure compliance with WhatsApp's Terms of Service and local regulations. \ No newline at end of file