High-performance TypeScript implementation of the WhatsApp Web protocol.
Built for high-scalability workloads, multi-session operation, and full user configurability.

📚 Documentation: zapo.to · 🛠 Contributing: CONTRIBUTING.md · 💛 Sponsor: GitHub Sponsors

---

Stability Notice

zapo-js is stable as of 1.0.0. The public API follows SemVer: breaking changes ship only in a major release; minors add features, patches fix bugs.

Install

npm install zapo-js

Zero mandatory runtime dependencies. Pick the optional packages you need on top: a persistent store, the media processor for thumbnails / voice-note metadata, and the native crypto accelerator.

# Persistent store - choose one
npm install @zapo-js/store-sqlite better-sqlite3
# or @zapo-js/store-redis ioredis
# or @zapo-js/store-postgres pg
# or @zapo-js/store-mysql mysql2
# or @zapo-js/store-mongo mongodb

# Optional - thumbnails + waveforms + voice-note normalization
npm install @zapo-js/media-utils sharp
# plus a system `ffmpeg` + `ffprobe` on PATH (see media-utils README)

# Optional - Rust crypto accelerator, no code change required
npm install @zapo-js/native

# Optional - structured logging
npm install pino pino-pretty

@zapo-js/native is picked up automatically once installed: the core resolves it on first use and falls back to the JS implementation when it is absent, so nothing else changes. It accelerates the two primitives that dominate the messaging hot path, X25519 ECDH and XEdDSA sign / verify. The published build is the WASM one (ZAPO_NATIVE_BACKEND=auto tries the NAPI addon first, then WASM); the compiled NAPI addon is not on npm yet and has to be built from packages/native. Set ZAPO_NATIVE_BACKEND=js to opt out.

Quick Start

import { ConsoleLogger, createStore, WaClient } from 'zapo-js'
import { createSqliteStore } from '@zapo-js/store-sqlite'

const store = createStore({
    backends: {
        sqlite: createSqliteStore({ path: '.auth/state.sqlite' })
    },
    providers: {
        auth: 'sqlite',
        signal: 'sqlite',
        preKey: 'sqlite',
        session: 'sqlite',
        identity: 'sqlite',
        senderKey: 'sqlite',
        appState: 'sqlite',
        privacyToken: 'sqlite',
        messages: 'sqlite', // 'none' to skip the message archive
        threads: 'sqlite', // 'none' to skip
        contacts: 'sqlite' // 'none' to skip
    }
})

const client = new WaClient({ store, sessionId: 'default' }, new ConsoleLogger('info'))

client.on('auth_qr', ({ qr }) => {
    console.log('scan this:', qr)
})

client.on('auth_paired', ({ credentials }) => {
    console.log('paired as', credentials.meJid)
})

client.on('message', async (event) => {
    if (event.message?.conversation === 'ping') {
        await client.message.send(event.key.remoteJid, 'pong')
    }
})

await client.connect()

That's the minimum to pair, listen for messages, and reply. For everything else - sending media, reactions, polls, groups, newsletters, app-state mutations, business profile, events catalog, store providers, the typed event map, and the architectural reasoning - read the guides at zapo.to.

Packages

The core lives at the repo root (zapo-js). Optional packages live in packages/ and ship under the @zapo-js/* scope. Install only what you need.

Package	Peer dependency	Purpose
@zapo-js/store-sqlite	better-sqlite3	SQLite persistent store (single-process bots, dev sessions, small-to-medium prod).
@zapo-js/store-redis	ioredis	Redis-backed store with native TTL eviction.
@zapo-js/store-mongo	mongodb	MongoDB-backed store with TTL-index eviction.
@zapo-js/store-mysql	mysql2	MySQL / MariaDB-backed store with background cleanup poller.
@zapo-js/store-postgres	pg	PostgreSQL-backed store with background cleanup poller.
@zapo-js/media-utils	sharp + file-type + ffmpeg	WaMediaProcessor: thumbnails, waveforms, voice-note normalization.
@zapo-js/native	(none)	Rust crypto accelerator for the messaging hot path (X25519 ECDH, XEdDSA sign / verify). Auto-detected once installed; ships as a WASM build.
@zapo-js/voip	@roamhq/wrtc + libmlow-wasm	client.voip plugin for calls: MLow/WASM codec, SRTP, STUN, WebRTC/SCTP relay transport.
@zapo-js/wam	(none)	client.wam plugin emitting the client-side WAM telemetry batches WA Web sends, for wire parity and anti-fingerprinting.
@zapo-js/fake-server	(none)	In-process fake WhatsApp Web server for end-to-end testing.
@zapo-js/mcp-server	@modelcontextprotocol/sdk	Dev-only. MCP server exposing multi-session WaClients as dynamic tools for an LLM agent (Claude Code / Cursor / etc.). Not for production.

Each package's README has the install + config + integration notes.

Documentation

• zapo.to - guides, full API reference, examples, protocol notes (llms.txt index or llms-full.txt for LLM context)
• vinikjkkj/zapo-docs - source of zapo.to (open issues/PRs there for doc fixes)
• Per-package READMEs under packages/ - one per optional package
• AGENTS.md - architecture spec + coding rules (contributor-facing)

Contributing

Pull requests are welcome. See CONTRIBUTING.md for setup, repo layout, CI, release flow, and the conventions PRs must follow.

Contributors also agree to the Code of Conduct, which includes an AI-Assisted Contributions policy covering disclosure, human ownership, and the rule against bundle-hallucinated protocol claims.

Security

Found a vulnerability in the crypto, auth, or Signal layer? Please do not open a public issue. Report it privately via GitHub Security Advisories or email contact@vinicius.email. Scope, response window, and disclosure timeline are documented in SECURITY.md.

License

MIT © vinikjkkj

Support the Project

If zapo is useful in your production or study setup, you can support ongoing development on GitHub Sponsors: github.com/sponsors/vinikjkkj.

Disclaimer

This project is an independent implementation for engineering and interoperability research. It is not affiliated with or endorsed by WhatsApp.