Prerequisites
Relevant source files
The following files were used as context for generating this wiki page:Before using the WhatsApp Chat Analytics tool, several software packages must be installed, and specific data files must be acquired from your Android phone and WhatsApp Web. This setup ensures that the decryption and analysis processes can run locally on your machine, keeping your data private. The project is divided into a Python-based chatsExporter for decryption and a Node.js-based web application for analysis.
The prerequisites can be categorized into three main areas: software installation, data acquisition, and environment configuration. Fulfilling these requirements is essential for the successful operation of both parts of the project.
Sources: README.md:1-20
Overall Prerequisite Flow
The following diagram illustrates the high-level flow of setting up the necessary prerequisites.
This diagram shows the sequence of installing software, gathering required data files, and configuring the local environment before the tool can be used.
Sources: README.md:22-34, chatsExporter/whatsapp_db_android_exporter.py:3-8
Software Requirements
The project relies on both Python for backend decryption and Node.js for the frontend web application.
Sources: README.md:15-16
Core Technologies
| Technology | Required Version | Purpose | Source File |
|---|---|---|---|
| Python | 3.9 or newer | Runs the chatsExporter script to decrypt .crypt15 backup files. | README.md:23 |
| Node.js | 18 or newer | Runs the React-based web application for searching and visualizing chat data. | README.md:24 |
Python Dependencies
The chatsExporter script requires the wa-crypt-tools library to handle the decryption of WhatsApp's database files. The script is designed to automatically install this dependency via pip if it's not found.
wa-crypt-tools: A Git-based dependency installed to provide thewacreatekeyandwadecryptcommand-line utilities. The installation is triggered within theensure_wa_tools_installedfunction.
Sources: chatsExporter/whatsapp_db_android_exporter.py:32-41
Node.js Dependencies
The web application uses several key libraries to function. These are installed by running npm install in the web/ directory.
| Dependency | Purpose |
|---|---|
react | Core library for building the user interface. |
sql.js | A library to run SQLite queries directly in the browser, enabling local data processing. |
rsuite | A UI component library used for elements like date pickers, selectors, and uploaders. |
@amcharts/amcharts5 | Used for creating the data visualization charts. |
crypto-browserify | A polyfill required for cryptographic operations in the browser, configured in config-overrides.js. |
Sources: web/package.json:5-23, config-overrides.js:5-7
Data Requirements
To analyze your chats, you must first gather three key pieces of data.
Sources: README.md:25-29
Data Acquisition Flow
This diagram details the steps to acquire the necessary files from your phone and browser.
This sequence shows the user interaction with their phone and WhatsApp Web to obtain the encrypted database and the chat list JSON.
Sources: README.md:36-72
Required Files and Data
| Item | Description | How to Obtain |
|---|---|---|
| WhatsApp Backup File | The encrypted database file, typically ending in .crypt15. | Create a local backup on your Android phone and transfer it from Android/media/com.whatsapp/WhatsApp/Databases. |
| Encryption Key | A 64-character hexadecimal string used to decrypt the backup file. | Obtained when setting up end-to-end encrypted backups in WhatsApp. |
| Chat List JSON | A model-storage-chat.json file containing a list of your conversations. | Exported by running a JavaScript snippet in the developer console of WhatsApp Web. |
The web application's upload step explicitly asks for the decrypted msgstore.db (a result of processing the .crypt15 file) and the model-storage-chat.json file.
Sources: README.md:25-29, web/src/Pages/SearchSQLite/components/UploadStep.jsx:38-63
Environment Configuration
After installing the software and gathering the data, a small amount of configuration is needed.
chatsExporter Configuration
The Python decryption script requires an .env file to be configured in the chatsExporter/ directory.
- Copy
.env.exampleto.env. - Edit the
.envfile to provide the following values:ENCRYPTION_KEY: Your 64-character WhatsApp backup encryption key.TARGET_DIR: The directory path where your.crypt15backup files are located.
The script will read these environment variables to find the key and the target database for decryption.
Sources: README.md:51-57, chatsExporter/whatsapp_db_android_exporter.py:90-94
web Application Setup
The web application requires its Node.js dependencies to be installed before it can be run.
- Navigate to the
web/directory. - Run the command
npm install.
This command reads web/package.json and installs all necessary libraries into the node_modules folder. After installation, the application can be started with npm start.
Sources: README.md:75-77, web/package.json:25-28