README.md

# WhatsApp Chatbot (Ultimate Edition v3.0)

**Project ID:** 8
**Category:** Custom Chatbots
**Difficulty:** Advanced
**Author:** RSK World
**Website:** [rskworld.in](https://rskworld.in)
**Contact:** info@rskworld.com | +91 93305 39277

## Description
A feature-rich **WhatsApp-integrated chatbot solution**. Version 3.0 introduces **Multilingual support**, **Broadcasting capabilities**, and a full-fledged **Admin Dashboard**. This project is designed for real-world usage with essential business features, including sentiment analysis, urgency detection, and appointment management.

## 🚀 Key Features

### 🤖 Intelligent Chat Bot
* **Multilingual Support**: Instant toggle between **Hindi** and **English** languages (`hindi`/`english`).
* **Fuzzy Matching**: Smartly handles typos (e.g., "boking" -> "booking").
* **Contextual Memory**: Remembers user state for multi-step conversations.
* **Sentiment Analysis**: Analyzes user mood (Positive/Negative/Neutral).
* **Urgency Detection**: Automatically flags messages with keywords like "urgent".
* **Interactive Menu**: Structured menu navigation for services and support.
* **Joke Engine**: Adds personality with random joke generation.
* **Fallback Handling**: Graceful responses for unrecognized inputs.
* **Session Management**: Robust in-memory user session tracking.
* **State Machine**: Guided flows for complex tasks like booking.
* **Knowledge Base**: Fuzzy search over predefined service descriptions.
* **Greeting Recognition**: Natural greeting handling in multiple languages.
* **Conversation Reset**: `reset` command to clear user session context.
* **Admin Escalation**: Intelligent routing for negative sentiment queries.

### 📊 Powerful Admin Dashboard
* **Live Analytics**: Real-time sentiment charts validation.
* **Booking Watchtower**: Centralized view of all customer appointments.
* **Broadcast System**: Send mass marketing messages to all users.
* **CSV Export**: One-click download of all booking data for Excel.
* **User Management**: View details of interacting users and histories.
* **Status Tracking**: Monitor booking implementation statuses visually.
* **Sentiment Trends**: Visual distribution of user satisfaction levels.
* **Recent Activity**: Live feed of user intents and interactions.
* **Secure Access**: Admin route protection logic.
* **Responsive Design**: Mobile-friendly Bootstrap 5 dashboard interface.
* **Data Visualization**: Interactive charts using Chart.js.
* **Total Interaction Count**: Track overall system usage metrics.
* **Broadcast Simulation**: Safe testing mode for broadcast features.

### 🌟 Key Capabilities
* **Appointment Booking**: Multi-step conversational booking flow.
* **Emergency Detection**: Prioritizes urgent messages automatically.
* **Broadcasting**: Marketing/Announcement capability via API.
* **Bilingual**: Hindi and English support out of the box.
* **Cross-Platform**: Works on WhatsApp Mobile, Web, and Desktop.
* **Zero-Database Setup**: No SQL setup required to get started.
* **Cloud Ready**: Configured for immediate cloud deployment.
* **User-Centric Design**: Focus on natural conversational flow.
* **Rapid Prototyping**: Ideal base for MVP development.

## 💻 Technologies
* **Python 3.10+**: Leveraging modern language features.
* **Flask Framework**: Lightweight, flexible, and powerful backend.
* **Twilio API**: Industry-standard WhatsApp integration.
* **Bootstrap 5**: Modern, responsive UI framework for dashboard.
* **Chart.js**: Beautiful, reactive data visualization libraries.
* **TextBlob**: Advanced Natural Language Processing (NLP).
* **TheFuzz**: High-performance string matching and deduplication.
* **JSON Storage**: Lightweight, serverless flat-file database.
* **REST API**: Clean API architecture for frontend communication.
* **Jinja2 Templating**: Dynamic HTML rendering for admin pages.

## 📂 Project Structure
* `app.py`: Main Flask application entry point and route handlers.
* `bot_logic.py`: Core AI logic, state management, and NLP processing.
* `templates/`: Jinja2 HTML templates for Admin Dashboard.
* `static/`: CSS, JavaScript, and Image assets directory.
* `bookings.json`: Portable JSON database for appointment data.
* `analytics.json`: Storage for sentiment and interaction logs.
* `requirements.txt`: Complete dependency list for easy installation.
* `Procfile`: Deployment configuration for Heroku/Cloud platforms.
* `runtime.txt`: Python version specification for environments.

## Setup & Running

1. **Install dependencies:**
```bash
pip install -r requirements.txt
```

2. **Download NLTK Corpora (if needed):**
```bash
python -m textblob.download_corpora
```

3. **Run the application:**
```bash
python app.py
```

4. **Access:**
- **App**: `http://localhost:5000/`
- **Dashboard**: `http://localhost:5000/admin`

## 🙏 Credits & Acknowledgments
* [Flask](https://flask.palletsprojects.com/) - Web Framework
* [Twilio](https://www.twilio.com/) - WhatsApp API
* [Bootstrap 5](https://getbootstrap.com/) - UI Framework
* [TextBlob](https://textblob.readthedocs.io/) - NLP Library
* [TheFuzz](https://github.com/seatgeek/thefuzz) - Fuzzy String Matching
* [RSK World](https://rskworld.in) - Project Creator

© 2026 RSK World. All rights reserved.