Add README.md
This commit is contained in:
commit
87ca24ea46
|
|
@ -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.
|
||||||
Loading…
Reference in New Issue