Case study

whatsapp-web-reveng: documenting the legacy WhatsApp Web protocol

Documents and reimplements the WebSocket protocol WhatsApp Web used while browser sessions mirrored a paired phone: QR pairing, Curve25519/HKDF key setup, AES/HMAC-protected binary messages, the token-based node encoding and end-to-end media encryption. A Python backend, Node.js relay and browser front end decode a logged-in session’s messages into inspectable JSON, and the README lists independent reimplementations such as Baileys and go-whatsapp. This is an older protocol generation from before WhatsApp’s 2021 multi-device architecture, not a description of current WhatsApp Web.

Targets: Protocol · Website
Category: Independent reconstruction cases
Relationship: Independent reconstruction project
Sources reviewed: 2026-10-19

Requirements & limits

Prerequisites: Use needs the user’s own WhatsApp account and phone to scan the pairing code, and the backend connects to WhatsApp’s servers. The protobuf definitions come from a helper script that parses the public WhatsApp Web JavaScript bundle. The README’s task list still names growing binary-decoding errors, writing binary messages and a less technical interface as open work.
Prerequisites: Bare-metal setup needs Node.js 8+ and Python 2.7 with websocket-client, simple-websocket-server, curve25519-donna, pycrypto (pycryptodome in requirements.txt), pyqrcode and protobuf; Windows also needs Visual C++ for Python 9.0 and a supplied header. A shell.nix (Python 2.7, Node.js 13) and a Dockerfile are provided, and npm start runs the backend, Node API and front end together. The README says the Docker version is not stable enough for production.
Scope: Reviewed at the 2024-04-22 master head, a README-only change; the backend and Node relay last changed in August 2021, the protobuf schema in March 2020, and there are no releases or tags. The README’s pairing flow has the phone supply session details such as its battery level, the phone-mirroring companion model that WhatsApp’s July 2021 engineering post says multi-device replaces. A 2022 issue reports the server answering a QR scan with an upgrade_md_prod command. As checked on 2026-10-20, the 2024-04-22 head is still GitHub’s last recorded push, the repository is not archived and the README does not mark it as maintained, superseded or archived.
Testing evidence: There is no test suite: the package.json test script only starts the components. The documented correctness checks are HMAC validation of the server’s key data and of each binary message, and an in-browser JavaScript demo prints decrypted messages after a QR scan.
License: MIT (LICENSE, package.json). The README states the project is unaffiliated with and not endorsed by WhatsApp, that use is at the user’s own risk, and adds a cryptography export notice; WhatsApp’s services and terms apply separately.

About this entry

The description was reviewed against primary sources.

Report an outdated entry Suggest a translation fix

Primary sources

README.md GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
backend/whatsapp.py GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
backend/whatsapp_binary_reader.py GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
doc/spec/def.proto GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
doc/spec/protobuf-extractor/index.js GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
package.json GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
requirements.txt GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
shell.nix GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
Dockerfile GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
LICENSE GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
https://github.com/sigalor/whatsapp-web-reveng/issues/372
https://engineering.fb.com/2021/07/14/security/whatsapp-multi-device/

Requirements & limits

About this entry

Primary sources

More in Websites