WhatsApp Bot with Web and Mobile Control Interface

A comprehensive WhatsApp automation bot with a beautiful web interface, built with TypeScript and modern web technologies.

🚀 Features

Simple Features

• ✅ Auto-Reply to Messages
• ✅ Welcome/Goodbye Messages
• ✅ Keyword-Based Commands
• ✅ Message Forwarding
• ✅ Scheduled Messages
• ✅ Basic Moderation
• ✅ Media Sharing
• ✅ Basic Scam/Spam Detection
• ✅ Auto-View Status
• ✅ Download Status to Device

Intermediate Features

• 🔄 User Profile Analysis
• 🔄 Multi-Language Support
• 🔄 Interactive Menus
• 🔄 Group Event Notifications
• 🔄 Message Analytics
• 🔄 Integration with External APIs
• 🔄 Role-Based Access
• 🔄 Automated Group Invites
• 🔄 Save View-Once Media to Device
• 🔄 Turn View-Once Media into WhatsApp Sticker

Complex Features

• 🔄 Advanced Scam/Spam Detection
• 🔄 Database Integration
• 🔄 Webhook-Based Automation
• 🔄 Multi-Group Management
• 🔄 AI-Powered Chatbot
• 🔄 User Behavior Profiling
• 🔄 Automated Moderation Actions
• 🔄 Custom Interactive Flows
• 🔄 Real-Time Dashboard
• 🔄 Cross-Platform Notifications
• 🔄 Scalable Infrastructure

🏗️ Architecture

whatsapp-bot/
├── bot/                    # Core WhatsApp bot (whatsapp-web.js)
├── backend/               # REST API (Express.js)
├── frontend/              # Web interface (React + Chakra UI)
├── mobile/                # Future mobile app (React Native)
└── docs/                  # Documentation

🛠️ Technology Stack

• Bot: whatsapp-web.js, wa-sticker-formatter, sharp
• Backend: Node.js, Express, mongoose, redis, jsonwebtoken
• Frontend: React, TypeScript, Chakra UI, recharts, axios
• Database: MongoDB Atlas
• Deployment: Heroku/AWS, Netlify/Vercel, Redis Cloud

🚀 Quick Start

Prerequisites

• Node.js 18+
• MongoDB
• Redis (optional)
• WhatsApp account for testing

Installation

1. Clone and setup:

   git clone https://github.com/icekidtech/whatsapp-bot.git
   cd whatsapp-bot
   pnpm install

2. Setup bot:

   cd bot
   pnpm install
   pnpm run build

3. Setup backend:

   cd ../backend
   pnpm install
   pnpm run build

4. Setup frontend:

   cd ../frontend
   pnpm install
   pnpm run build

5. Environment variables: Create .env files in each module with required configurations.

Running the Application

1. Start all services:

   pnpm run install:all
   pnpm run dev

2. Or run individually:

   # Terminal 1 - Bot
   cd bot && pnpm run dev
   
   # Terminal 2 - Backend
   cd backend && npm run dev
   
   # Terminal 3 - Frontend
   cd frontend && npm start

3. Access the web interface:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:3001
   • API Docs: http://localhost:3001/api/health

📱 Web Interface

The web interface provides:

• Dashboard: Real-time bot status and analytics
• Feature Management: Toggle features on/off
• Log Viewer: Monitor bot activity and messages
• Analytics: Detailed usage statistics
• Settings: Configure bot parameters

Demo Credentials

• Username: admin
• Password: admin

🔧 Configuration

Environment Variables

Bot (.env)

BOT_NAME=WhatsApp Bot
BOT_PREFIX=!
MONGODB_URI=mongodb://localhost:27017/whatsapp-bot
REDIS_URL=redis://localhost:6379
SESSION_PATH=./.wwebjs_auth

Backend (.env)

PORT=3001
MONGODB_URI=mongodb://localhost:27017/whatsapp-bot
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key

📊 API Endpoints

Configuration

• GET /api/config/status - Get bot status
• POST /api/config/toggle-feature - Toggle feature
• POST /api/config/restart - Restart bot
• GET /api/config/features - List features

Logs

• GET /api/logs - Get logs
• GET /api/logs/messages - Get message logs
• DELETE /api/logs - Clear logs

Analytics

• GET /api/analytics - Get analytics
• GET /api/analytics/messages - Message analytics
• GET /api/analytics/features - Feature analytics

🔒 Security & Compliance

WhatsApp Terms Compliance

• Limited automation frequency
• Transparent user notifications
• Secondary phone number recommended
• Regular session refresh

Privacy Protection

• Encrypted media storage
• GDPR/CCPA compliance
• User consent for data collection
• Secure API endpoints

🚀 Deployment

Development

pnpm run dev

Production

pnpm run build
pnpm start

Docker (Future)

docker-compose up -d

📈 Implementation Phases

Phase 1 (Current) - Simple Features ✅

• Basic bot functionality
• Web interface with toggles
• Local testing

Phase 2 - Intermediate Features 🔄

• Enhanced features
• Analytics dashboard
• Cloud deployment

Phase 3 - Complex Features 🔄

• AI integration
• Advanced moderation
• Multi-group management

Phase 4 - Mobile App 📱

• React Native implementation
• Push notifications
• Mobile-specific features

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

📝 License

MIT License - see LICENSE file for details.

⚠️ Disclaimer

This project uses whatsapp-web.js which may violate WhatsApp's Terms of Service. Use at your own risk and ensure compliance with WhatsApp's policies. The developers are not responsible for any account bans or violations.

📞 Support

For support and questions:

• Create an issue on GitHub
• Check the documentation in /docs
• Review the PRD for detailed specifications

---

Version: 1.0 Author: Udoh, Idopise Edwin Date: September 2025