Skip to main content

Documentation Index

Fetch the complete documentation index at: https://zapo.to/llms.txt

Use this file to discover all available pages before exploring further.

​
Requirements

zapo requires Node.js >= 20.9.0. The package ships dual ESM/CJS builds and full TypeScript types.

​
Install the core package

npm install zapo-js
The core package has no mandatory runtime dependencies. Everything else — storage, logging, and the WebSocket transport — is an opt-in peer dependency, so you only install what you use.

​
Add a storage backend

zapo persists authentication and Signal state through a pluggable store. Pick the backend that matches your deployment and install its package:
PackageBackendBest for
@zapo-js/store-sqliteSQLite (via better-sqlite3)Local / single-process
@zapo-js/store-postgresPostgreSQLDistributed, relational
@zapo-js/store-mysqlMySQLDistributed, relational
@zapo-js/store-redisRedisCache + persistence
@zapo-js/store-mongoMongoDBDocument store
npm install @zapo-js/store-sqlite better-sqlite3
You can also run with no backend at all — the built-in memory store works out of the box and is great for tests. It just does not survive a process restart, so you would re-pair on every boot.

​
Optional peer dependencies

Install these only if you use the corresponding feature: 
npm install pino pino-pretty
  • pino + pino-pretty — required only if you use createPinoLogger. Without them, the built-in ConsoleLogger is used.
  • ws — only needed to route the WebSocket through a proxy. The runtime’s native WebSocket can’t take an HTTP Agent/dispatcher, so zapo falls back to ws for the proxy.ws leg. Without a proxy, the built-in WebSocket is used and you don’t need this package.
  • argo-codec — only needed for mobile connections (for now). The standard companion (QR / pairing-code) flow does not use it.

​
Sending media

@zapo-js/media-utils is effectively required to send usable media. Media still uploads without it, but there’s no processor to generate thumbnails/previews, image-video dimensions, or voice-note waveforms — so it can render as a plain attachment or with no preview. Install it whenever your app sends images, video, audio, documents, or stickers.
npm install @zapo-js/media-utils
It shells out to ffmpeg/ffprobe and uses sharp, so make sure those binaries are available. See the media guide for how to wire the processor into the client.

​
Verify your setup

import { WaClient } from 'zapo-js'

console.log(typeof WaClient) // "function"
Next, head to the quickstart to connect and send your first message.
Last modified on May 27, 2026