WhatsApp Export Unpacker

January 27, 2026 · View on GitHub

A Python tool with a local web UI for extracting, reconstructing, and preserving WhatsApp chat exports. Designed for digital forensics, evidence preservation, and investigative workflows.

How to Export a WhatsApp Chat

Before using this tool, you need to export a chat from WhatsApp:

On Android

Open WhatsApp and navigate to the chat you want to export
Tap the three-dot menu in the top right
Select More → Export chat
Choose Include media when prompted
Select a destination (email, cloud storage, or file manager)
The export will be saved as a ZIP file

View step-by-step screenshots

Step 1	Step 2	Step 3

Step 4	Step 5

On iOS

Open WhatsApp and navigate to the chat you want to export
Tap the contact/group name at the top
Scroll down and tap Export Chat
Choose Attach Media when prompted
Select a destination (AirDrop, email, Files, etc.)
The export will be saved as a ZIP file

What's in the Export?

The ZIP file contains:

A .txt file with the chat history
Voice messages (.opus files)
Images (.jpg, .png, etc.)
Videos (.mp4, etc.)
Other shared files

This tool provides a local web interface for processing WhatsApp chat export ZIP files. It reconstructs chats into multiple formats suitable for analysis, archival, and presentation—with automatic transcription of audio and video using OpenAI's Whisper API.

Use Cases

Digital Forensics — Preserve and organize chat evidence with full media inventories
Evidence Preservation — Generate archival-quality PDFs with transcribed voice messages
Investigations — Create searchable, structured outputs from raw WhatsApp exports
Legal Documentation — Produce presentation-ready HTML and PDF formats
Privacy — Anonymize participant names before sharing or archiving

Features

Web-Based Interface — WhatsApp-themed drag-and-drop UI with a gradient background matching WhatsApp's signature green
Interactive Statistics — Grid display showing message counts, participant counts, voice messages, videos, and images at a glance
Archive Extraction — Unpacks WhatsApp export ZIP files and organizes contents
Chat Parsing — Identifies participants, timestamps, and message types with date range detection
Voice Transcription — Transcribes audio messages using OpenAI Whisper API
Video Transcription — Extracts and transcribes audio from video files
Participant Anonymization — Multiple alias styles (Human Names, Generic, Codenames) plus custom name support
PDF Generation — Creates formatted PDF documents via Typst
HTML Viewer — Produces a static HTML page that simulates the WhatsApp interface
Live Preview — Inline HTML preview directly in the results page

Screenshots

Web Interface Workflow

Step 1: Upload & Statistics

After uploading, view chat statistics and configure processing options:

Statistics and Options

Step 2: Anonymize Participants

Choose how to display each participant - keep original, random alias, or custom name:

Anonymization

Custom Name

Step 3: Processing

Processing

Step 4: Results

Download generated files including PDF, HTML viewer, and chat reconstruction:

Results

Step 5: HTML Viewer with Transcriptions

The HTML viewer shows voice messages with automatic Whisper transcriptions:

HTML Viewer

CLI Version Screenshots

For reference, the CLI version produces similar outputs:

Constructed Chat	HTML Viewer	PDF Output

Installation

Requirements

Python 3.10+
FFmpeg (for audio/video processing)
Typst (optional, for PDF generation)

Quick Setup (Recommended)

# Clone the repository
git clone https://github.com/danielrosehill/WhatsApp-Export-Unpacker.git
cd WhatsApp-Export-Unpacker

# Run the installer
./install.sh

The installer will:

Create a virtual environment using uv
Install all dependencies (Flask, OpenAI, etc.)
Set up the .env file for API configuration

Manual Setup

If you prefer manual setup or don't have uv installed:

# Create virtual environment
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt

Or with standard pip:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

API Key Configuration

Copy the example environment file and add your API key:

cp .env.example .env

Then edit .env and add your OpenAI API key:

OPENAI_API_KEY=sk-your-api-key-here

You can get an API key at: https://platform.openai.com/api-keys

Optional: Install Typst for PDF Generation

# Via cargo
cargo install typst-cli

# Or via package manager (Ubuntu/Debian)
sudo apt install typst

Usage

Starting the Web UI

After running ./install.sh, launch the web interface:

./wa-unpack

Then open http://127.0.0.1:5000 in your browser.

Using the Web Interface

Upload — Drag and drop your WhatsApp export ZIP file onto the upload zone (or click to browse). The zone features a WhatsApp-themed green gradient with visual feedback during upload.
Review Statistics — After upload, a statistics grid displays:
- Total messages
- Number of participants
- Voice message count
- Video count
- Image count
- Date range (first to last message)
Configure Processing Options:
- Transcribe Voice Messages — Convert .opus audio to text via OpenAI Whisper (enabled by default)
- Transcribe Videos — Extract and transcribe audio from video files
- Generate PDF — Create a formatted PDF document via Typst (enabled by default)
- Generate HTML Viewer — Create an interactive chat viewer (enabled by default)
Anonymize Participants — A table displays each participant with their message count. For each:
- Keep — Use their original name
- Random — Generate an alias from the selected style
- Custom — Enter your own replacement name
Choose an Alias Style from the dropdown:
- Human Names — Alice, Bob, Carol, etc.
- Generic — Participant A, Participant B, etc.
- Codenames — Alpha, Bravo, Charlie, etc.
Process — Click "Process Export" to generate outputs. A progress bar shows processing status.
Results — View generated files with download buttons. If HTML was generated, an inline preview displays the chat viewer directly in the browser. Click "Process Another Export" to start over.

Output Structure

output/
├── elements/
│   ├── constructed-chat.txt  # Reconstructed with transcriptions
│   ├── chat.typ              # Typst source file
│   ├── chat.pdf              # Generated PDF
│   └── chat.html             # Interactive HTML viewer
├── analysis/
│   └── participants.json     # Participant statistics
└── extracted/
    ├── *.opus                # Voice messages
    ├── *.jpg                 # Images
    ├── *.mp4                 # Videos
    └── ...                   # Other media files

How It Works

Upload & Parse — The ZIP file is uploaded, extracted, and parsed to detect participants, messages, and media. Statistics are calculated and displayed in a grid.
Configuration — Select processing options (transcription, PDF, HTML) and configure participant anonymization with your preferred alias style.
Processing — The backend processes the export:
- Voice messages (.opus files) are converted and transcribed via OpenAI Whisper
- Videos are optionally transcribed by extracting their audio
- Participant names are replaced with aliases if configured
- A consolidated chat file is generated with transcriptions inserted inline
- A Typst source file is created and compiled to PDF (if enabled)
- An interactive HTML page simulating the WhatsApp interface is generated (if enabled)
Results — Generated files are listed with download buttons. HTML output includes an inline preview iframe showing the reconstructed chat.

Dependencies

Package	Purpose
`flask`	Web UI framework
`openai`	Whisper API for transcription
`python-dotenv`	Environment variable management

System Dependencies

Tool	Purpose	Required
`ffmpeg`	Audio/video format conversion	Yes (for transcription)
`typst`	PDF compilation	Optional

Limitations

Requires OpenAI API key for voice/video transcription
WhatsApp export format may vary by platform/version
Large exports with many voice messages may incur API costs
Web UI is designed for single-user local use

Privacy & Security

This tool processes personal chat data. Please be aware:

Local processing: All file extraction and parsing happens locally on your machine
Local web server: The Flask server runs only on localhost (127.0.0.1)
API calls: Voice/video transcriptions are sent to OpenAI's Whisper API. Review OpenAI's data usage policy
No data collection: This tool does not collect, store, or transmit any data beyond the Whisper API calls
Output storage: Generated files remain on your local system—handle them according to your security requirements
Sensitive content: Chat exports may contain personal information, media, and private conversations. Store outputs securely and share responsibly
Anonymization: Use the anonymization feature to protect participant identities before sharing

For maximum privacy, disable transcription options to skip all API calls entirely.

Troubleshooting

"No chat text file found in ZIP"

The export may be malformed or from an unsupported WhatsApp version. Verify the ZIP contains a .txt file with chat messages.

Transcription fails with "Could not convert opus file"

FFmpeg is required for audio conversion. Install it:

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows
# Download from https://ffmpeg.org/download.html

PDF generation fails

Typst is optional but required for PDF output. Install it:

# Via cargo
cargo install typst-cli

# Ubuntu/Debian (if available)
sudo apt install typst

"Invalid API Key" error

Verify your OpenAI API key is correctly set in .env:

cat .env  # Should show OPENAI_API_KEY=sk-...