Skip to main content

​
Requisitos

O zapo requer Node.js >= 20.9.0. O pacote entrega builds duais ESM/CJS e tipos TypeScript completos.

​
Instale o pacote principal

O pacote principal não tem dependências de runtime obrigatórias. Todo o resto — armazenamento, logging e o transporte WebSocket — é uma peer dependency opt-in, então você instala apenas o que usa.

​
O ecossistema de pacotes

zapo-js é o único install obrigatório. Todo o resto é um pacote opcional @zapo-js/* que você adiciona conforme a necessidade:
zapo-js — client core, coordinators, contrato de store
@zapo-js/store-sqlite — backend SQLite
@zapo-js/store-postgres — backend PostgreSQL
@zapo-js/store-mysql — backend MySQL
@zapo-js/store-redis — backend Redis
@zapo-js/store-mongo — backend MongoDB
@zapo-js/media-utils — thumbnails, probes, waveforms
@zapo-js/voip — chamadas de voz do WhatsApp
@zapo-js/wam — paridade de telemetria do WhatsApp Web (analytics)
@zapo-js/native — acelerador cripto opcional Rust NAPI + WASM
@zapo-js/mcp-server — ferramenta dev: controle por um agente de IA
@zapo-js/fake-server — ferramenta dev: servidor de teste in-process

​
Adicione um backend de armazenamento

O zapo persiste o estado de autenticação e do Signal por meio de uma store plugável. Escolha o backend que combina com o seu deployment e instale o pacote dele:
Você também pode rodar sem backend algum — a store em memória embutida funciona de imediato e é ótima para testes. Ela apenas não sobrevive a um restart do processo, então você teria que reparear a cada boot.

​
Peer dependencies opcionais

Instale-as apenas se você usar a funcionalidade correspondente:
  • pino + pino-pretty — necessários apenas se você usar createPinoLogger. Sem eles, o ConsoleLogger embutido é usado.
  • ws — necessário apenas para rotear o WebSocket através de um proxy. O WebSocket nativo do runtime não consegue receber um Agent/dispatcher HTTP, então o zapo recorre ao ws para a perna proxy.ws. Sem um proxy, o WebSocket embutido é usado e você não precisa deste pacote.
  • argo-codec — necessário apenas para conexões mobile (por enquanto). O fluxo companion padrão (QR / código de pareamento) não o usa.

​
Enviando mídia

O @zapo-js/media-utils é efetivamente necessário para enviar mídia utilizável. A mídia ainda faz upload sem ele, mas não há processor para gerar thumbnails/previews, dimensões de imagem-vídeo ou waveforms de notas de voz — então ela pode aparecer como anexo simples ou sem preview. Instale-o sempre que seu app enviar imagens, vídeo, áudio, documentos ou figurinhas.
Ele invoca ffmpeg/ffprobe e usa sharp, então garanta que esses binários estejam disponíveis. Veja o guia de mídia para saber como conectar o processador ao client.
@zapo-js/media-utils também lista file-type (^19) como peer dependency opcional. Instale-o (npm install file-type) para habilitar a detecção automática de mimetype — sem ele, a resolução de mimetype do guia de mídia volta a exigir um mimetype explícito em cada envio.

​
Chamadas de voz

Instale @zapo-js/voip para fazer e receber chamadas de voz do WhatsApp. Ele é distribuído como um plugin de WaClient e puxa duas peer dependencies próprias:
  • @roamhq/wrtc — SCTP para o transporte de relay.
  • libmlow-wasm — perfil Opus do WhatsApp, em WebAssembly (sem build nativo).
Veja o guia de VoIP para saber como conectar voipPlugin() ao client.

​
Paridade de telemetria

Instale @zapo-js/wam para que a sessão emita as batches de analytics client-side w:stats que uma aba real do WhatsApp Web envia — uma melhoria de paridade de wire / anti-fingerprinting, não obrigatória para mensageria.
A única peer dependency é zapo-js. O registry de eventos WAM (@vinikjkkj/wa-wam) é fixado como dependencies regular do plugin, então vem transitivamente. Veja o guia WAM para saber como conectar wamPlugin() ao client. É opt-in: pule-o a menos que você especificamente queira a paridade.

​
Acelerador de crypto nativo

Instale @zapo-js/native para tirar o hot path de crypto de mensageria do JavaScript puro — sign/verify XEdDSA (que domina o SKDM sign no fanout de grupo) e ECDH scalar mult X25519 (evitando o round-trip DER do node:crypto.diffieHellman) — para um core em Rust distribuído como build WebAssembly. Sem toolchain, sem compile pós-install.
O zapo-js faz try-require do binding no carregamento do módulo; quando o pacote (ou seu binário nativo) está ausente, o path JS puro assume e o client funciona sem alteração. Instalá-lo é sempre seguro.
Requer Node.js >= 20.19.0: carregar o glue WASM depende de require(esm), disponível sem flag apenas em 20.19+ / 22.12+. Em runtimes mais antigos o client silenciosamente cai de volta para o path JS puro.
Duas variáveis de ambiente forçam o path JS por primitiva, úteis para medir A/B ou como kill switch:
  • ZAPO_XEDDSA_FORCE_JS=1 — força JS para XEdDSA sign/verify.
  • ZAPO_X25519_FORCE_JS=1 — força JS para X25519 scalar mult.
Para desabilitar o acelerador por completo, defina ZAPO_NATIVE_BACKEND=js antes do processo iniciar. Veja o README do pacote para detalhes da seleção de backend.

​
Verifique sua configuração

A seguir, vá para o quickstart para conectar e enviar sua primeira mensagem.
Última modificação em 1 de agosto de 2026