📱 WhatsApp Chat Analyzer

A Streamlit dashboard that takes an exported WhatsApp chat (.txt file) and turns it into a full analytics report — message stats, activity timelines, heatmaps, word clouds (Bengali + English), emoji analysis, and an optional AI-generated weekly summary powered by Gemini.

Built as a personal project to explore group chat behavior using Python, Pandas, Plotly, and NLP techniques on mixed-language (Bengali / Banglish / English) data. Runs great on Google Colab, tunneled to a public URL with ngrok.

---

Demo Video

streamlit-app-2026-07-19-12-12-14.mp4

---

Features

• Chat Statistics — total messages, words, media, links, and VCF contact cards shared, for the whole group or one member.
• Timeline Analysis — daily and monthly message frequency line charts.
• Activity Patterns — most active days of the week, most active months, and hour-by-hour activity.
• Heatmaps — GitHub-style daily activity heatmap, weekday vs month heatmap, day-of-month vs month heatmap, and a dark-themed weekly schedule heatmap (time of day vs day of week).
• Member Analysis — top active members (bar + pie chart), chat starters and enders (who sends the first/last message of the day), and a sunburst chart (Year → Month → Weekday → Member).
• Word Analysis — top frequent words with a custom Bengali/Banglish stopword list (500+ words), plus separate word clouds for Bengali script and English/Banglish script.
• Emoji Analysis — most used emojis with counts and share percentage.
• Message Length Distribution — box plot comparing message length across top senders.
• AI Summary (optional) — a 7-day chat summary generated by Google Gemini, with caching so it only runs once per selection instead of on every page interaction.

All charts use a consistent Material Design color palette.

---

Tech Stack

Purpose	Library
Web app / UI	Streamlit
Data handling	Pandas
Charts	Plotly Express
Word cloud	WordCloud
Emoji parsing	emoji
Link extraction	urlextract
AI summary	Google Gemini SDK and API
Public tunnel (Colab)	pyngrok

---

Project Structure

.
├── app.py                        # Streamlit app entry point (UI + layout)
├── ngrok_run.py                  # Launches the app through an ngrok tunnel (for Colab)
├── utils.py                      # Core analysis and plotting functions
├── dataset_preprocess.py         # Parses raw WhatsApp .txt export into a DataFrame
├── data_clean.py                 # Text cleaning and tokenization helpers
├── config.py                     # Paths, stopwords, font, and API keys (see Setup below)
├── gemini_agent/
│   ├── gemini_halper.py          # GeminiHelper class (Gemini API wrapper)
│   ├── gemini_prompt.py          # Prompt templates (e.g. weekly summary)
│   └── gemini_utils.py           # Helpers like "get last N days of messages"
├── assets/
│   ├── font/
│   │   └── Siyamrupali.ttf       # Bengali font used for word clouds
│   └── stopwords/
│       ├── stopwords_bengali.txt
│       ├── stopwords_banglish.txt
│       └── stopwords_english.txt
├── notebook/
│   └── whatsapp-chat-analyzer.ipynb
├── requirements.txt                  # Minimal dependencies to run the app
├── requirements-all.txt              # Full pinned environment (e.g. for Colab)
└── README.md

---

How It Works

1. Export a chat from WhatsApp — open a chat, tap the three-dot menu, choose More → Export Chat → Without Media. This gives you a .txt file.
2. Upload the file in the sidebar of the app.
3. dataset_preprocess.py parses the raw text into a structured Pandas DataFrame (sender, message, date, time, etc.).
4. data_clean.py normalizes and tokenizes messages for word/word-cloud analysis, using the stopword lists in assets/stopwords.
5. utils.py runs all the statistics and builds every chart shown on the dashboard.
6. Pick Overall or a specific member from the sidebar dropdown, then click Show Analysis.
7. Optionally turn on AI Summary to get a Gemini-generated summary of the last 7 days of chat.

---

Setup

1. Clone the repository

git clone https://github.com/codebysumit/whatsapp-chat-analyzer.git
cd whatsapp-chat-analyzer

2. Install dependencies

pip install -r requirements.txt

Use requirements-all.txt instead if you want the full pinned environment (closer to the Colab setup).

The Bengali font and stopword files are already included in the repo under assets/, so no extra download is needed.

3. Add your API keys

Open config.py and replace the placeholder values with your own keys:

GEMINI_API_KEYS = [
    "gemini_api_key1",
    "gemini_api_key2",
]
NGROK_AUTH_TOKEN = "ngrok_auth_token"

Get a Gemini key from aistudio.google.com/apikey and an ngrok token from dashboard.ngrok.com.

4. Run the app

Locally:

streamlit run app.py

The app opens at http://localhost:8501.

On Google Colab (no direct browser access, so use the ngrok tunnel):

python ngrok_run.py

This starts Streamlit and prints a public ngrok URL you can open in any browser.

---

License

This project is licensed under the MIT License.

---

Author

Sumit (@codebysumit) Diploma in Cyber Forensics and Information Security, Behala Government Polytechnic, Kolkata LinkedIn · codebysumit@gmail.com