Add README.md

2025-09-23 19:32:39 +00:00 · 2025-09-23 19:32:39 +00:00 · 87ca24ea46
commit 87ca24ea46
1 changed files with 337 additions and 0 deletions
--- a/README.md
+++ 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.