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-fork | client.voip plugin for calls: MLow/WASM codec, SRTP, STUN, WebRTC/SCTP relay transport. | | @zapo-js/voip-media | libmlow-wasm-fork (optional, to carry media) + @roamhq/wrtc (optional, Node host) | Call media plane with no Node or zapo-js dependency, so it runs in the browser: relay transport, STUN, SRTP, RTP/RTCP, MLow codec. | | @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,

• vinikjkkj/zapo-docs -

• Per-package READMEs under packages/ - one per

• AGENTS.md - architecture spec + coding rules

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 [email protected]. 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.