Step 1: Obtaining WhatsApp Backup Files

This document outlines the initial and most critical phase of the WhatsApp Chat Analytics workflow: acquiring and preparing the necessary data files for analysis. This process involves several distinct parts, starting from creating a backup on an Android device, decrypting the encrypted database, exporting a list of chats, and finally uploading the prepared files into the web application. The entire process is designed to be performed locally on the user's machine, ensuring that private message data is never sent over the internet.

The process is broken down into four main parts: creating the backup, decrypting it, exporting the chat list, and uploading the resulting files. Once these files are obtained, the user can proceed to Step 2: Search & Filter and Step 3: View Results.

Sources: README.md, web/src/Pages/SearchSQLite/index.jsx:7-9

Overall Data Acquisition Flow

The following diagram illustrates the high-level journey from a user's Android phone to having the required files ready for the analysis application.

This diagram shows the four distinct stages of data acquisition required before analysis can begin.
Sources: README.md:29-106

Part 1: Backup Creation and Transfer

The process begins with the user creating a local backup of their WhatsApp data on their Android device. This backup is not a Google Drive backup but a local file stored on the phone's internal storage.

1. Create Backup: The user must manually trigger a backup within the WhatsApp application.
2. Locate Backup File: The encrypted backup file is typically a .crypt15 file located at Android/media/com.whatsapp/WhatsApp/Databases on the device's storage.
3. Transfer to PC: The user must transfer this .crypt15 file to their computer. This can be done via a USB cable or using the Android Debug Bridge (adb) with the following command:

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

Sources: README.md:32-42

Part 2: Decrypting the Backup (.crypt15 to .db)

The .crypt15 file is encrypted and cannot be used directly. The chatsExporter Python script is provided to decrypt this file into a readable SQLite database (.db).

Sources: README.md:14, README.md:44-63

Configuration

Before running the decryption script, the user must configure it by creating and editing a .env file in the chatsExporter/ directory.

Sources: README.md:50-55, chatsExporter/whatsapp_db_android_exporter.py:4-6

Decryption Logic

The whatsapp_db_android_exporter.py script orchestrates the decryption process by leveraging the wa-crypt-tools library.

The following flowchart details the script's execution flow:

This diagram shows the internal steps of the whatsapp_db_android_exporter.py script, from configuration loading to the final decrypted database file.
Sources: chatsExporter/whatsapp_db_android_exporter.py:72-139

Key functions involved in this process are:

• main(): Orchestrates the entire process.
• validate_hex_key(): Ensures the ENCRYPTION_KEY is a 64-character hex string.
• ensure_wa_tools_installed(): Installs wa-crypt-tools via pip if not present.
• create_key_file_from_hex(): Runs the wacreatekey command to generate a key file from the hex key.
• decrypt_files(): Runs the wadecrypt command to convert the .crypt15 file into a .db file.

Sources: chatsExporter/whatsapp_db_android_exporter.py

Part 3: Exporting the Chat List (model-storage-chat.json)

To map chat IDs to user/group names, the web application requires a JSON file containing a list of all chats. This file is obtained by running a JavaScript snippet in the browser's developer console on WhatsApp Web.

The process is as follows:

1. Open https://web.whatsapp.com and wait for chats to load.
2. Open the browser's Developer Tools (F12).
3. Navigate to Sources -> Snippets.
4. Create a new snippet and paste the contents of chatsExporter/dumbWAChats.js.
5. Run the snippet, which will automatically download model-storage-chat.json.

Sources: README.md:65-81

The dumbWAChats.js script accesses the browser's IndexedDB where WhatsApp Web stores chat information.

The sequence diagram below shows how the script works:

This diagram illustrates the script's interaction with the browser's IndexedDB to extract and download the chat list.
Sources: chatsExporter/dumbWAChats.js

Part 4: Uploading Files to the Web Application

The final step of data acquisition is to upload the two generated files (msgstore.db and model-storage-chat.json) into the local web application. The application presents a three-step interface, with the first step dedicated to file uploads.

Sources: README.md:100-106, web/src/Pages/SearchSQLite/index.jsx:10-12

Upload UI

The UploadStep component provides two drag-and-drop areas for the required files.

This diagram shows the flow within the UploadStep component, from UI rendering to enabling navigation to the next step.
Sources: web/src/Pages/SearchSQLite/components/UploadStep.jsx, web/src/Pages/SearchSQLite/index.jsx:21-32, 78-91

File Validation and Parsing

When files are uploaded, the FileService class is used to validate and process them.

• Validation: The service checks the file extensions to ensure the correct files are being uploaded.
  • Messages file must be .db.
  • Chats file must be .json.
• Parsing:
  • The .db file is read as an ArrayBuffer.
  • The .json file is read as text and then parsed. The parseChatFile method transforms the raw JSON data into a structured list of chats with id, name, and type properties for use in the application.

Sources: web/src/Pages/SearchSQLite/services/fileService.js:5-16, 39-55

Conclusion

Obtaining and preparing the WhatsApp backup files is a multi-part but straightforward process that forms the foundation for all subsequent analysis. By decrypting the database and exporting the chat list locally, the user prepares the necessary data for the web application's analysis tools while maintaining complete control and privacy over their chat history. Successful completion of these steps unlocks the ability to search, filter, and visualize message data.