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

git clone https://git.classy.id/andri/whatsapp-hybrid-gateway.git
cd whatsapp-hybrid-gateway

2. Install dependencies

npm install

3. Configure environment

cp .env.example .env
nano .env

4. Start the application

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

# 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

GET /

Send Text Message

curl -X POST http://localhost:5000/api/send-message \
  -H "Content-Type: application/json" \
  -d '{"phone":"6281234567890","message":"Hello World!"}'

Send Image

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

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

sudo nano /etc/systemd/system/whatsapp-gateway.service

2. Service configuration

[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

sudo systemctl daemon-reload
sudo systemctl enable whatsapp-gateway
sudo systemctl start whatsapp-gateway

PM2 Process Manager

# 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

# 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

# View real-time logs
sudo journalctl -u whatsapp-gateway -f

# View recent logs
sudo journalctl -u whatsapp-gateway --since "1 hour ago"

PM2 Monitoring

# Monitor processes
pm2 monit

# View logs
pm2 logs whatsapp-gateway

# Restart if needed
pm2 restart whatsapp-gateway

Health Checks

# 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 file for details.

Acknowledgments

• Baileys - WhatsApp Web API library
• Express.js - Web framework
• 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.