Pular para o conteúdo principal

Documentation Index

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

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

O zapo foi feito para cargas de trabalho longevas e multi-sessão. Esta página reúne as decisões operacionais que importam quando você passa do protótipo local.

​
Persista as credenciais (não refaça o pareamento)

Sessões de produção precisam usar uma store durável para os domínios auth e Signal, além de um sessionId estável entre reinícios. A store em memória perde tudo ao sair, forçando um novo pareamento a cada boot. 
const client = new WaClient({ store, sessionId: 'tenant-42' }, logger)
Trocar o sessionId deixa as credenciais anteriores órfãs — trate-o como a chave durável de um dispositivo/conta.

​
Escolha um backend de store

BackendMelhor para
@zapo-js/store-sqliteProcesso único / host único — a opção local mais simples e rápida.
@zapo-js/store-postgres · @zapo-js/store-mysqlMúltiplos hosts, operações relacionais, backups gerenciados.
@zapo-js/store-redisCache de baixa latência + persistência.
@zapo-js/store-mongoDeployments orientados a documentos.
Você pode misturar backends por domínio (ex.: auth/signal no Postgres, caches no Redis). Veja Instalação e a referência de stores.

​
Shutdown gracioso

Chame disconnect() (nunca logout()) no shutdown — ele descarrega os dados pendentes de write-behind e fecha o socket sem desvincular o dispositivo, então o próximo boot retoma a partir da store. 
for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.on(signal, async () => {
    await client.disconnect()
    process.exit(0)
  })
}
logout() desvincula o dispositivo no servidor e limpa o estado armazenado — força um novo pareamento completo. Use-o apenas para desconectar permanentemente, nunca como hook de shutdown.

​
Rode muitas sessões

Uma única store pode conter muitas contas independentes, cada uma indexada por sessionId. Crie um WaClient por conta: 
const clients = tenants.map((id) => new WaClient({ store, sessionId: id }, logger))
await Promise.all(clients.map((c) => c.connect()))
Cada client pareia, reconecta e emite eventos de forma independente. Reserve memória/CPU por sessão (cada uma mantém estado Signal e caches em memória) e faça sharding entre processos/hosts conforme escala — um processo por sessão é o modelo de isolamento mais simples. Veja multi-tenancy.

​
Ajuste para throughput

  • Write-behind agrupa as escritas de mensagens/threads/contatos fora do hot path. Ajuste writeBehind.maxPendingKeys / maxWriteConcurrency / flushTimeoutMs ao seu banco. (config)
  • History sync (history.enabled) adiciona um download inicial grande. Deixe desligado a menos que precise de backfill, e use requireFullSync deliberadamente.
  • Bots que não devem aparecer online: defina markOnlineOnConnect: false.
  • Timeouts (iqTimeoutMs, keepAliveIntervalMs, deadSocketTimeoutMs, …) vêm com padrões de produção — sobrescreva só com motivo. (config)

​
Política de reconexão & erros

O zapo não reconecta sozinho — assuma a política. Ligue um loop de backoff (Reconexão) e classifique as falhas (Erros & desconexões) para parar em razões fatais (banned, not_authorized, logout) em vez de martelar o servidor.

​
Logging

Use um logger estruturado em produção: 
const logger = await createPinoLogger({ level: 'info', pretty: false })
pretty: false emite linhas JSON adequadas a agregadores de log. Caia para debug / trace só ao investigar.

​
Segurança & versionamento

  • Credenciais são segredos. WaAuthCredentials contém as chaves do dispositivo — se você as persistir fora da store embutida, criptografe em repouso. (Autenticação)
  • Nunca habilite dangerous.* em produção — essas flags desabilitam verificações de segurança. (config)
  • Fixe versões exatas. O zapo é pré-1.0; breaking changes são esperadas até o primeiro release maior.
Last modified on May 28, 2026