An intelligent AI-powered WhatsApp bot that brings conversational AI capabilities to personal and group chats. Built with Google Gemini 2.0 Flash and modern AI orchestration techniques.
📌 Note: This is a public documentation-only repository.
The actual source code lives in a private repository and is not open source at the moment.
This project demonstrates a sophisticated AI assistant that integrates seamlessly with WhatsApp. Users can interact with the bot using simple trigger commands, and it responds with intelligent, context-aware answers powered by Google's latest Gemini AI model.
Perfect for:
- Personal productivity and quick information lookup
- Group chat assistance and Q&A
- Learning AI integration patterns
- Building custom AI-powered chat solutions
- Powered by Google Gemini 2.0 Flash for fast, accurate responses
- Context-aware conversations that understand intent
- Configurable response styles and creativity levels
- Works in both personal and group chats
- Multiple trigger patterns (
!ask,@bot,@ai,>) - Real WhatsApp Web integration (not unofficial APIs)
- Self-message testing capability
- Customizable trigger commands
- Authorization controls (whitelist specific numbers)
- Adjustable response length and AI temperature
- Enable/disable for different chat types
- Beautiful Streamlit-based web interface
- Real-time message statistics and analytics
- Response time tracking
- Test environment for trying queries
- Comprehensive logging system
- Runs locally on your machine
- No third-party data sharing
- You control all configurations and data
- Open-source and transparent
Simply message your WhatsApp with a trigger command:
!ask What is quantum computing?
The bot processes your message and responds with:
Quantum computing uses quantum-mechanical phenomena like
superposition and entanglement to perform computations.
Unlike classical computers that use bits (0 or 1), quantum
computers use qubits which can exist in multiple states
simultaneously, enabling them to solve certain problems
exponentially faster...
!ask Explain machine learning in simple terms
@bot Tell me a joke
@ai What's the capital of France?
> Summarize the benefits of exercise
The system uses a sophisticated multi-agent orchestration approach:
┌─────────────────────────────────────┐
│ WhatsApp Messages │
└──────────────┬──────────────────────┘
│
┌──────▼──────┐
│ Trigger │
│ Detection │
└──────┬──────┘
│
┌──────▼──────────┐
│ Agent │
│ Orchestrator │
└──────┬──────────┘
│
┌──────────┼──────────┐
│ │ │
┌───▼───┐ ┌──▼───┐ ┌──▼────┐
│ Q&A │ │ MCP │ │Memory │
│ Agent │ │Tools │ │ Agent │
└───┬───┘ └──┬───┘ └──┬────┘
│ │ │
└─────────┼─────────┘
│
┌─────▼──────┐
│ Response │
│ Back to │
│ WhatsApp │
└────────────┘
The web dashboard provides comprehensive monitoring:
- Total messages processed
- Average response time
- Activity charts and trends
- Agent performance metrics
- Live feed of conversations
- Query and response pairs
- Timestamp and processing time
- Chat type indicators
- Try queries without sending WhatsApp messages
- Quick test scenarios
- Performance benchmarking
- Response preview
- System configuration display
- Connection health status
- Available WhatsApp chats
- Error tracking
The system is highly customizable through environment variables:
| Setting | Description | Example |
|---|---|---|
| Triggers | Commands that activate the bot | !ask,@bot,@ai,> |
| Authorization | Whitelist specific phone numbers | +1234567890,+9876543210 |
| Group Chats | Enable/disable group chat responses | true or false |
| AI Model | Gemini model version | gemini-2.0-flash |
| Response Length | Maximum words in response | 500 |
| Temperature | AI creativity level (0.0-1.0) | 0.7 |
WhatsApp Bridge Layer
- Go-based WhatsApp Web client
- REST API server (Port 3334)
- SQLite database for message persistence
- QR code authentication
AI Orchestration Layer
- Message processor with trigger detection
- Agent orchestrator for routing
- Agent registry for extensibility
- Confidence scoring system
AI Agent Layer
- Google Gemini 2.0 Flash integration
- LangGraph-based conversation flow
- MCP (Model Context Protocol) support
- Extensible tool system
Management Layer
- Streamlit dashboard (Port 8503)
- Real-time analytics
- Comprehensive logging
- Testing interface
- AI/ML: Google Gemini 2.0 Flash, LangChain, LangGraph
- Backend: Python 3.10+, Go 1.19+
- WhatsApp: whatsapp-mcp bridge
- Database: SQLite
- Dashboard: Streamlit
- APIs: REST, WebSocket
- Deployment: Docker, Cloud-ready
- Quick information lookup while messaging
- Code assistance and debugging
- Language translation
- Math and calculation help
- Answer common questions automatically
- Provide information to group members
- Fun interactions and engagement
- Educational Q&A sessions
- Study AI integration patterns
- Understand multi-agent systems
- Learn WhatsApp automation
- Explore LangChain/LangGraph
- Customer support automation
- Internal team assistance
- Knowledge base access
- FAQ handling
✅ Production-Ready: Built with error handling, logging, and monitoring
✅ Extensible: Modular architecture for adding new agents and tools
✅ Privacy-Focused: Runs locally with no third-party data sharing
✅ Well-Documented: Comprehensive code documentation and guides
✅ Modern Stack: Uses latest AI models and frameworks
✅ Real Integration: Works with actual WhatsApp Web (not unofficial APIs)
Building or studying this project teaches:
- Multi-agent AI system design
- WhatsApp integration patterns
- REST API development
- Real-time monitoring dashboards
- AI orchestration with LangGraph
- Message processing pipelines
- Configuration management
- Error handling and logging
- All processing happens locally on your machine
- No message data sent to third parties (except Gemini API for AI responses)
- Authorization controls to restrict access
- Open-source code for transparency
- You control all data and configurations
This project builds upon excellent work from:
- whatsapp-mcp by Luke Harries - WhatsApp integration foundation
- Google Gemini AI - Powerful language model
- LangChain & LangGraph - AI orchestration frameworks
- Streamlit - Beautiful dashboard framework
This is a showcase repository demonstrating the project's capabilities. The full implementation is maintained in a private repository.
Interested in:
- Building something similar?
- Collaborating on AI projects?
- Learning more about the architecture?
Feel free to reach out or star this repo to show your interest!
⚡ Bringing AI intelligence to everyday conversations
A demonstration of modern AI integration with WhatsApp