The `chatsExporter` Component
Relevant source files
The following files were used as context for generating this wiki page:
The chatsExporter component is a Python command-line tool designed to decrypt encrypted WhatsApp backup files (.crypt15) from Android devices. Its primary function is to convert these inaccessible backup files into a readable SQLite database (.db file), which can then be used for local analysis. This component is the first crucial step in the data processing pipeline of the whatsapp-chat-analytics project, enabling the web/ application to query and visualize chat data without it ever leaving the user's machine.
The overall project is divided into two main parts: the chatsExporter/ for decryption and the web/ application for analysis. The exporter prepares the necessary data files, which are then manually uploaded into the web interface.
Sources: README.md:10-14, chatsExporter/whatsapp_db_android_exporter.py
Architecture and Dependencies
The chatsExporter is a standalone Python script (whatsapp_db_android_exporter.py) that orchestrates several command-line operations. It has a critical external dependency on wa-crypt-tools, a third-party toolset that provides the wacreatekey and wadecrypt utilities necessary for handling WhatsApp's encryption.
The script is designed to be self-contained; it checks for the presence of these utilities and, if they are not found, attempts to install them automatically using pip from their GitHub repository.
Sources: chatsExporter/whatsapp_db_android_exporter.py:31-40
This diagram shows the dependency of the main exporter script on the external wa-crypt-tools.
Configuration
The script's behavior is controlled by a combination of environment variables loaded from a .env file and constants defined at the top of the script.
Environment Variables
A .env file is required in the chatsExporter directory to provide the necessary credentials and paths.
| Variable | Description | Example |
|---|---|---|
ENCRYPTION_KEY | The 64-character hexadecimal key for decrypting the WhatsApp backup. | 1a2b3c... |
TARGET_DIR | The directory path containing the .crypt15 backup files. Defaults to the current directory (.) if not set. | ./backups |
Sources: chatsExporter/whatsapp_db_android_exporter.py:6-8, 92-95
Script Constants
These constants can be modified directly within the Python script for advanced configuration.
| Constant | Description | Default Value |
|---|---|---|
KEYFILE_PATH | Path to a pre-existing .key file. If set, the script skips key creation. | None |
FORCE_INSTALL | If True, forces the re-installation of wa-crypt-tools. | False |
DEFAULT_KEY_FILENAME | The default name for the key file generated by wacreatekey. | "encrypted_backup.key" |
Sources: chatsExporter/whatsapp_db_android_exporter.py:20-23
Execution Flow
The main() function in whatsapp_db_android_exporter.py defines the step-by-step process for decryption. The script is designed to be run from the command line and will exit with different status codes depending on the outcome.
The following flowchart illustrates the main execution path of the script.
Key Functions
The script is modularized into several key functions that handle specific parts of the decryption process.
ensure_wa_tools_installed(force: bool)
This function checks if the wacreatekey and wadecrypt command-line tools are available in the system's PATH. If they are not, or if the force parameter is True, it executes a pip install command to download and install the wa-crypt-tools package from its GitHub repository. It raises an error if the tools are still not found after the installation attempt.
Sources: chatsExporter/whatsapp_db_android_exporter.py:31-40
validate_hex_key(hex_input: str)
Responsible for sanitizing and validating the ENCRYPTION_KEY. It uses a regular expression to remove any non-hexadecimal characters (like spaces or dashes) and then checks if the resulting string is exactly 64 characters long. It raises a ValueError if the key is invalid.
Sources: chatsExporter/whatsapp_db_android_exporter.py:43-49
create_key_file_from_hex(hex_key: str)
This function takes the validated 64-character hex key and uses it to invoke the wacreatekey utility. It runs the command wacreatekey --hex <hex_key>, which generates a binary .key file. The function then locates this newly created file and returns its absolute path.
Sources: chatsExporter/whatsapp_db_android_exporter.py:52-63
decrypt_files(keyfile: str, crypt_files: List[str])
This is the core decryption function. It iterates over a list of .crypt15 file paths. For each file, it constructs and executes a wadecrypt command, passing the key file path, the encrypted input file, and a generated output file name (e.g., msgstore_2023-10-27.db).
Sources: chatsExporter/whatsapp_db_android_exporter.py:69-75
Outputs and Consumption
The chatsExporter process produces the primary data artifact required for analysis: the decrypted SQLite database.
Data Artifacts
msgstore.db: The main output of thewhatsapp_db_android_exporter.pyscript. This is a standard SQLite database containing all message data, chat information, and more.model-storage-chat.json: While not generated by the Python script, the project's documentation outlines a manual process to export this file from WhatsApp Web. It contains a list of chats and their metadata, which is used by the web app to display chat names correctly.
Sources: README.md:86-116, web/src/Pages/SearchSQLite/components/UploadStep.jsx:28-31, 51-54
Consumption by the Web App
The web application (web/) is designed to consume these two files. The UploadStep component in the UI provides distinct upload areas for the msgstore.db and model-storage-chat.json files. Once both are uploaded, the user can proceed to the search and analysis steps, where the web application will use libraries like sql.js to query the database directly in the browser.
This diagram shows the data flow from the export process to the web application.