WhatsApp Chat Analytics

Unlock and analyze your WhatsApp chat history from Android backups. Everything runs on your own computer — your messages stay private and never leave your device.

What This Tool Does

• Unlocks encrypted backups: Converts your encrypted WhatsApp backup files (.crypt15) into a readable database
• Analyzes your chats locally: Lets you search and analyze your messages in a web browser without uploading anything to the internet
• Filters and explores: Search by date, media type (photos, videos, etc.), sender, or specific conversations
• Visual insights: See charts showing your messaging activity and get statistics about your chats

How It's Organized

This project has two parts:

• chatsExporter/ — A Python tool that unlocks your encrypted backup files
• web/ — A web application where you can search and analyze your messages

What You'll Need

Before starting, make sure you have:

1. Python 3.9 or newer installed on your computer (Download here)
2. Node.js 18 or newer installed (Download here)
3. Your WhatsApp encryption key (a 64-character code needed to unlock backups)
4. Your WhatsApp backup files (.crypt15 files from your Android phone)
5. A list of your chats exported as a JSON file

Step-by-Step Guide

Note for Mac/Linux users: The commands shown are for Windows PowerShell. You may need to adjust them slightly for your system.

Step 0: Create and Transfer Your Backup

First, you need to get your WhatsApp backup files from your phone to your computer.

1. Create a backup: Watch this video (watch until 01:39) for instructions on creating your WhatsApp backup file
2. Find the backup: On your Android phone, the backup is located at:
   Android/media/com.whatsapp/WhatsApp/Databases
3. Transfer to PC: You can copy the file as you want, or use this command if you have adb installed:

adb pull /storage/emulated/0/Android/media/com.whatsapp/WhatsApp/Databases ./

Step 1: Unlock Your Encrypted Backups

Now we'll convert the encrypted backup into a usable database file.

1. Navigate to the decryption tool folder:

cd ".\chatsExporter"

2. Set up your configuration:

cp .env.example .env

3. Edit the .env file (open it with Notepad or any text editor) and fill in:

   • ENCRYPTION_KEY — Your 64-character WhatsApp backup encryption key
   • TARGET_DIR — The folder path where you saved your .crypt15 backup files

4. Run the decryption tool:

python whatsapp_db_android_exporter.py

The tool will create unlocked database files (.db files) in the same folder as your backup files.

Step 2: Get Your Chat List

The web application needs a list of your chats to display names properly. Here's how to export it:

1. Open WhatsApp Web at https://web.whatsapp.com in your browser
2. Wait for all your chats to load completely
3. Press F12 to open Developer Tools
4. Go to the Sources tab, then click Snippets
5. Click + New snippet to create a new one
6. Open the file dumpWAChats.js from this project, copy all its contents
7. Paste the code into the snippet you just created
8. Click the Run button (play icon) at the bottom
9. The browser will automatically download a file called model-storage-chat.json

Step 3: Analyze Your Chats

Now for the fun part — exploring your chat history!

1. Start the web application:

cd ".\web"
npm install
npm start

2. Open your browser and go to http://localhost:3000

3. Follow the three steps in the application:

   • Step 1 (Upload Files):
     • Upload the msgstore.db file (created in Step 1)
     • Upload the model-storage-chat.json file (created in Step 2)
   • Step 2 (Search & Filter):
   • Step 3 (View Results):

Privacy & Security

• Everything stays on your computer: All analysis happens in your web browser. Your messages are never uploaded to the internet or sent to any server
• Only use your own data: Only decrypt and analyze backup files that belong to you

Important Disclaimer

This tool is designed for personal use. Please use it responsibly:

• Only analyze your own WhatsApp backups
• Respect privacy laws and terms of service
• Don't use this tool to access someone else's messages without permission
• This project is an independent, open-source effort and is not affiliated with, endorsed by, or sponsored by WhatsApp or Meta Platforms, Inc.
• You are solely responsible for how you use this software. Misuse may violate laws or WhatsApp’s Terms of Service and could lead to account restrictions, data loss, or legal consequences.
• Use at your own risk. The authors and contributors provide this software “as is” without any warranties or guarantees of any kind.