Configuração

O WaClient recebe um objeto WaClientOptions e um logger opcional:

const client = new WaClient(options, logger)

Apenas store e sessionId são obrigatórios; todo o resto tem um valor padrão sensato.

Opções obrigatórias

store

WaStore

obrigatório

A instância da store construída por createStore. Mantém cada domínio por sessão (auth, signal, app-state, …).

sessionId

string

obrigatório

Identificador lógico da sessão — ele indexa cada domínio dentro da store. Use uma string estável por dispositivo/conta. Trocá-lo entre execuções deixa as credenciais anteriores órfãs e força um novo pareamento.

Sessões e multi-tenancy

Como cada domínio da store é indexado por sessionId, uma única store pode conter muitas contas independentes. Para rodar várias contas em um processo, crie um WaClient por sessionId sobre a mesma store:

const store = createStore({ /* ... */ })

const accountA = new WaClient({ store, sessionId: 'account-a' }, logger)
const accountB = new WaClient({ store, sessionId: 'account-b' }, logger)

await Promise.all([accountA.connect(), accountB.connect()])

Cada client pareia e reconecta de forma independente. Esta é a base para deployments multi-tenant.

Fingerprint do dispositivo

Estes controlam como o dispositivo aparece em Dispositivos conectados no celular:

deviceBrowser

string

padrão:"'chrome'"

Id do navegador anunciado durante o pareamento ('chrome', 'firefox', 'safari', …; veja WA_BROWSERS). Define o rótulo em Dispositivos conectados.

devicePlatform

string

Sobrescrita do id numérico de plataforma companion (WA_COMPANION_PLATFORM_IDS). Inferido de deviceBrowser quando omitido; defina explicitamente para plataformas não-navegador.

new WaClient({ store, sessionId: 'default', deviceBrowser: 'Chrome' }, logger)

Sincronização de histórico

history

WaHistorySyncOptions

Controla o download inicial do histórico de mensagens.

enabled?: boolean — baixa o histórico na primeira sincronização.
requireFullSync?: boolean — solicita o arquivo completo em vez de apenas os chats recentes.

new WaClient({
  store,
  sessionId: 'default',
  history: { enabled: true, requireFullSync: true }
}, logger)

O histórico chega como eventos history_sync_chunk.

Timeouts

Todos em milissegundos; os padrões são ajustados para produção.

Opção	Propósito
`iqTimeoutMs`	Timeout padrão para queries IQ (padrão 60s).
`nodeQueryTimeoutMs`	Timeout padrão para chamadas brutas de `query()` de node.
`keepAliveIntervalMs`	Intervalo entre os IQs de ping de keep-alive.
`deadSocketTimeoutMs`	Quanto tempo sem resposta antes do socket ser considerado morto.
`mediaTimeoutMs`	Timeout de upload/download de mídia.
`appStateSyncTimeoutMs`	Timeout de uma rodada de sincronização de app-state.
`messageAckTimeoutMs`	Quanto tempo `message.send` espera pelo `<ack>` do servidor por tentativa.
`messageMaxAttempts`	Máximo de tentativas para um único `message.send`.
`messageRetryDelayMs`	Atraso entre as retentativas de envio de mensagem.

Presença ao conectar

markOnlineOnConnect

boolean

padrão:"true"

true — anuncia o client como online (igual ao WhatsApp Web com a aba em foco).
false — anuncia como indisponível. Útil para bots que não devem aparecer como online. Com isso desligado, você também continua recebendo notificações de mensagens enquanto está “offline”.

Addons (reações, votos em enquetes)

addons

{ autoDecrypt?: boolean }

Defina autoDecrypt: true para descriptografar automaticamente addons criptografados (votos em enquetes, reações, …) e emiti-los como eventos tipados message_addon. Caso contrário, chame client.message.tryDecryptAddon(event) você mesmo.

Persistência write-behind

writeBehind

WaWriteBehindOptions

Agrupa as mensagens recebidas em lotes antes de descarregá-las nas stores messages / threads / contacts.

maxPendingKeys?: number
maxWriteConcurrency?: number
flushTimeoutMs?: number

Proxy

proxy

WaClientProxyOptions

Roteie cada perna através de um proxy de forma independente:

ws — a conexão WebSocket.
mediaUpload / mediaDownload — transferências de mídia.
linkPreview — o fetcher padrão de preview de link.

Cada perna aceita um WaProxyTransport, que é:

um dispatcher do undici (WaProxyDispatcher, por exemplo um ProxyAgent do undici) — usado para as pernas baseadas em fetch (mídia, preview de link), ou
um Agent http/https do Node (WaProxyAgent) — usado para a perna WebSocket (ws).

O zapo escolhe a forma certa por perna automaticamente.

A perna ws requer o pacote ws, porque o WebSocket nativo do runtime não consegue aceitar um Agent HTTP. Sem um proxy, nenhum pacote extra é necessário.

Proxy HTTP / HTTPS

Use um ProxyAgent do undici (um dispatcher) para as pernas de mídia/preview de link, e um https-proxy-agent (um http.Agent) para a perna ws:

import { ProxyAgent } from 'undici'
import { HttpsProxyAgent } from 'https-proxy-agent'

const url = 'http://user:pass@proxy.example.com:8080' // ou https://…
const dispatcher = new ProxyAgent(url)
const wsAgent = new HttpsProxyAgent(url)

const client = new WaClient({
  store,
  sessionId: 'default',
  proxy: {
    ws: wsAgent,
    mediaUpload: dispatcher,
    mediaDownload: dispatcher,
    linkPreview: dispatcher
  }
}, logger)

Proxy SOCKS

Use socks-proxy-agent (funciona como um http.Agent para todas as pernas, incluindo ws):

import { SocksProxyAgent } from 'socks-proxy-agent'

// socks5 (ou socks4) — host pode ser um domínio ou um IP
const agent = new SocksProxyAgent('socks5://user:pass@127.0.0.1:1080')

const client = new WaClient({
  store,
  sessionId: 'default',
  proxy: { ws: agent, mediaUpload: agent, mediaDownload: agent, linkPreview: agent }
}, logger)

Hosts IPv4 e IPv6

O host do proxy pode ser um domínio ou um literal de IP. Endereços IPv6 devem ser envolvidos em colchetes:

// IPv4
new ProxyAgent('http://203.0.113.10:8080')
new SocksProxyAgent('socks5://203.0.113.10:1080')

// IPv6 — coloque o endereço entre colchetes
new ProxyAgent('http://[2001:db8::1]:8080')
new SocksProxyAgent('socks5://[2001:db8::1]:1080')

// Com credenciais
new ProxyAgent('http://user:pass@[2001:db8::1]:8080')

Aponte para o proxy apenas as pernas que você precisar — por exemplo, defina só ws para tunelar a conexão deixando a mídia transferir diretamente, ou vice-versa.

Limpeza da store no logout

logoutStoreClear

WaLogoutStoreClearOptions

Controle por domínio do que o logout() apaga. O padrão é limpar tudo; defina um domínio como false para preservá-lo.

// Mantém mensagens arquivadas e contatos após o logout
logoutStoreClear: { messages: false, contacts: false }

Logging

Passe um logger como o segundo argumento do construtor. Duas implementações vêm com o pacote:

import { ConsoleLogger, createPinoLogger } from 'zapo-js'

// Leve, sem dependências
const client = new WaClient(options, new ConsoleLogger('info'))

// Estruturado (requer `pino` + `pino-pretty`)
const logger = await createPinoLogger({ level: 'debug', pretty: true })
const client2 = new WaClient(options, logger)

Se você omitir o logger, um ConsoleLogger padrão é usado. Níveis de log: trace, debug, info, warn, error.

Opções perigosas

As flags dangerous desabilitam, cada uma, uma verificação de segurança que o caminho de produção aplica (verificação de assinatura, checagens de MAC do app-state, …). Elas existem para testes contra um servidor falso. Nunca as habilite em produção.

Documentation Index

​Opções obrigatórias

​Sessões e multi-tenancy

​Fingerprint do dispositivo

​Sincronização de histórico

​Timeouts

​Presença ao conectar

​Addons (reações, votos em enquetes)

​Persistência write-behind

​Proxy

​Proxy HTTP / HTTPS

​Proxy SOCKS

​Hosts IPv4 e IPv6

​Limpeza da store no logout

​Logging

​Opções perigosas

Opções obrigatórias

Sessões e multi-tenancy

Fingerprint do dispositivo

Sincronização de histórico

Timeouts

Presença ao conectar

Addons (reações, votos em enquetes)

Persistência write-behind

Proxy

Proxy HTTP / HTTPS

Proxy SOCKS

Hosts IPv4 e IPv6

Limpeza da store no logout

Logging

Opções perigosas