Transcribe a WhatsApp chat export, voice messages included

WhatsApp lets you export a chat, and the export is genuinely useful for about thirty seconds. You get a ZIP file with a text file of the conversation, and next to it a heap of media files with names like PTT-20260114-WA0007.opus (the voice messages). The text file just says that a voice message exists. What was actually said is in the audio, and nothing in the export reads it for you.

So I built WhatsApp Export Unpacker: a small Python tool with a local web interface that takes the export ZIP, parses the chat, transcribes the voice messages (and optionally the videos), and produces a readable version of the whole conversation. If you have been searching for how to read or transcribe a WhatsApp chat export, including the voice notes, this is my answer.

How to export a WhatsApp chat

The tool starts from the export, so the first step is making one. On Android: open the chat, tap the three-dot menu, then More, then Export chat, and choose Include media. On iOS: open the chat, tap the contact or group name, scroll down to Export Chat and choose Attach Media. Either way you end up with a ZIP file that you can send to yourself by email, cloud storage or AirDrop. The README has screenshots of the Android steps.

What is inside the ZIP: one .txt file with the chat history, the voice messages as .opus files, and whatever images, videos and other files were shared.

What the unpacker does

• Extracts the archive and parses the chat: participants, timestamps, message types and the date range.

• Shows a statistics grid up front: message count, participants, voice messages, videos and images.

• Transcribes voice messages with the OpenAI Whisper API (the code uses the whisper-1 model), converting the .opus files first so the API accepts them.

• Optionally extracts the audio from videos and transcribes that too.

• Rebuilds the chat as a text file with the transcriptions inline, a PDF (generated through Typst) and a static HTML page that imitates the WhatsApp interface.

• Optionally anonymises participants before you share or archive anything: keep the original name, take a random alias, or type a custom one. Alias styles are human names, generic (Participant A, B...) or codenames.

Installing it

You need Python 3.10 or newer and FFmpeg. Typst is optional and only needed for the PDF. The installer uses uv to make the virtual environment:

git clone https://github.com/danielrosehill/WhatsApp-Export-Unpacker.git
cd WhatsApp-Export-Unpacker
./install.sh

It also creates a .env file, where you put your OpenAI API key (Whisper is a paid API, so transcription is not free; the rest of the tool runs locally). Then:

./wa-unpack

and open http://127.0.0.1:5000 in a browser.

Using it

1. Drag the export ZIP onto the upload area.

2. Check the statistics, then pick what to generate: voice transcription, video transcription, PDF, HTML viewer.

3. If you want anonymisation, choose an alias style and set each participant to keep, random or custom.

4. Click Process Export and wait for the progress bar.

5. Download the results. If you made the HTML viewer, it also previews inline on the results page.

Everything lands in an output/ folder: elements/ holds constructed-chat.txt, the Typst source, the PDF and the HTML viewer; analysis/participants.json has per-participant statistics; extracted/ keeps the original media files, untouched.

What it is for, and what it is not

The README frames the use cases as evidence preservation, investigations and legal documentation, which is why the output is a PDF and a self-contained HTML page and why the originals are kept alongside. In my case it is simpler: a chat full of voice messages is hard to search and impossible to skim, and a transcript fixes both. (Transcription quality is Whisper's, so accents, noise and mixed languages will cost you accuracy. Check anything that matters against the audio.)

One thing to be aware of: the audio goes to OpenAI for transcription. If the chat is sensitive, that matters more than any feature in the list above.

Related projects

If what you really want is to dictate your own voice notes rather than process someone else's, AI Transcription Notepad is a voice note taking utility that uses cloud multimodal audio models for single-pass transcription and cleanup. For the other direction, sending and reading WhatsApp messages from an agent, I keep a private plugin built on the gateway's WAHA connection; that one is not public.

The code is at github.com/danielrosehill/WhatsApp-Export-Unpacker. It is MIT-licensed.