wa-proto-baron

Up-to-date Protocol Buffer definitions for WhatsApp Web, extracted directly from the live web client and shipped as a ready-to-use, strongly-typed protobuf.js module.

Includes the full WhatsApp app schema (WAProto) and the wa.voip calling schema reconstructed from WhatsApp's WebAssembly VoIP engine.

Installation

npm install wa-proto-baron

protobufjs is the only runtime dependency.

Usage

The package exports a single proto namespace containing every message and enum.

CommonJS

const { proto } = require('wa-proto-baron');

// encode
const bytes = proto.Message.encode(
  proto.Message.fromObject({ conversation: 'hello world' })
).finish();

// decode
const msg = proto.Message.decode(bytes);
console.log(msg.conversation); // "hello world"

// enums
proto.ADVEncryptionType.E2EE; // 0

ESM / TypeScript

import { proto } from 'wa-proto-baron';

const info: proto.IWebMessageInfo = {
  key: { remoteJid: '[email protected]', fromMe: true, id: 'ABC' },
  message: { conversation: 'hi' },
};

const encoded = proto.WebMessageInfo.encode(info).finish();

Full type declarations ship in dist/index.d.ts, so autocompletion and type checking work out of the box.

Raw .proto files

The schema sources are bundled too, for codegen in other languages or tooling:

• dist/WAProto.proto — combined WhatsApp app schema (package proto)
• dist/wa_voip.proto — VoIP/calling schema (package wa.voip)

const path = require('path');
const waProto = require.resolve('wa-proto-baron/dist/WAProto.proto');

What's included

| Source | Origin | Contents | | --- | --- | --- | | WAProto | WhatsApp Web JS bundles (internalSpec) | messages, app-state sync, history sync, payments, bots/AI, status, etc. | | wa.voip | whatsapp.wasm (protobuf-c, decoded) | call media/signaling: stream descriptors, subscriptions, rekey, feedback |

Development — regenerating the schema

The schema is rebuilt from a fresh copy of WhatsApp Web. All steps are wired as npm scripts.

npm install

# 1. download all WhatsApp Web JS bundles (+ static wasm) into downloads/
npm run download

# 2. build everything from the local mirror:
#    index.js -> dist/WAProto.proto, decode wasm -> wa.voip,
#    index2.js -> modular proto/ tree, generate + compile to dist/
npm run build:all

Or in one shot (download + build): npm run refresh.

Individual steps

| Script | Does | | --- | --- | | npm run download | Crawl & download every rsrc.php JS bundle + static .wasm | | npm run fetch | Extract dist/WAProto.proto from the bundles (index.js) | | npm run voip | Decode protobuf-c schemas from every downloads/**/*.wasm into wa.voip | | npm run fetch2 | Build the modular per-module proto/ tree (index2.js) | | npm run generate | Compile each proto/*.proto to JS/TS + aggregate index | | npm run compile | Compile dist/WAProto.proto to dist/index.js + dist/index.d.ts | | npm run check | Sanity-check the generated schema |

Order matters: voip appends to dist/WAProto.proto, which fetch regenerates — so build:all runs fetch → voip → fetch2 → generate → compile.

Capturing live / beta-only definitions

Some modules (beta features) and the VoIP whatsapp.wasm are loaded on demand and never appear in the static crawl. To capture them from a real session:

1. Start a browser with remote debugging:

   chrome --remote-debugging-port=9222

2. Open https://web.whatsapp.com/, log in, and exercise the features you want to capture (calls, AI, payments, …) so their bundles load.

3. Pull what the session loaded, then rebuild:

   npm run fetch-live    # all live-loaded JS + WASM  (or: npm run fetch-wasm for just the VoIP engine)
   npm run build:all

npm run voip automatically scans every .wasm found, so new engines are picked up on the next build.

Contributing

Contributions are welcome — open an issue or PR at https://github.com/7ucg/wa-proto-baron.

Disclaimer

This project is not affiliated with, authorized, or endorsed by WhatsApp or Meta. The definitions are provided for interoperability and research purposes only.

License

MIT — see LICENSE.