Reconexão

O WaClient não reconecta automaticamente. Esta é uma escolha de design deliberada: a política de reconexão (backoff, máximo de tentativas, alertas) pertence à sua aplicação. Você escuta o connection: close e decide o que fazer.

Camadas internas de recuperação

A regra “sem auto-reconnect” vale para o ciclo de vida da sessão: assim que um connection: close é emitido, o client não reabre sozinho. Mas dois retries de baixo nível existem dentro da stack – você os verá em log e não precisa tratá-los.

Transport WebSocket. Se o socket cair antes de um handshake noise bem-sucedido, o WaComms faz retry interno a cada reconnectIntervalMs (default 2000) até maxReconnectAttempts. Quando o handshake completa, o contador zera e qualquer queda posterior vira um evento connection pra sua app tratar.
Transição de pairing. Logo após um pair via QR/código, o client reinicia o socket como sessão já registrada. Nenhum connection: close é emitido – é invisível de fora.

A recuperação client_too_old (HTTP 405) coberta abaixo é uma terceira camada, opt-in.

Ciclo de vida da conexão

O evento connection

connection é uma union discriminada por status:

client.on('connection', (event) => {
  if (event.status === 'open') {
    console.log('connected', { isNewLogin: event.isNewLogin })
    return
  }

  // status === 'close'
  console.log('disconnected', {
    reason: event.reason,
    code: event.code,
    isLogout: event.isLogout
  })
})

Em close:

isLogout: true — o dispositivo foi desvinculado (logout no servidor). Não reconecte; as credenciais se foram e você precisa parear novamente.
isLogout: false — uma queda transitória. É seguro reconectar com as credenciais armazenadas.

Um loop de reconexão com backoff

const MAX_ATTEMPTS = 10

async function connectWithRetry(client: WaClient) {
  let attempt = 0

  client.on('connection', (event) => {
    if (event.status === 'open') {
      attempt = 0 // reseta o backoff em uma conexão saudável
      return
    }
    if (event.isLogout) {
      console.error('logged out — re-pairing required')
      return
    }
    void reconnect()
  })

  async function reconnect() {
    if (attempt >= MAX_ATTEMPTS) {
      console.error('giving up after', attempt, 'attempts')
      return
    }
    const delayMs = Math.min(30_000, 1_000 * 2 ** attempt)
    attempt += 1
    console.log(`reconnecting in ${delayMs}ms (attempt ${attempt})`)
    await new Promise((r) => setTimeout(r, delayMs))
    try {
      await client.connect()
    } catch (err) {
      console.error('reconnect failed', err)
      void reconnect()
    }
  }

  await client.connect()
}

Recuperando de `client_too_old` (HTTP 405)

Se o servidor começar a rejeitar o handshake noise com failure_client_too_old, a versão embarcada do WA Web está desatualizada. Duas opções:

Ative recoverFromClientTooOld: true no WaClient — a cada 405 o client busca a versão atual em web.whatsapp.com, troca em memória e reconecta.
Passe um resolver version que retorne uma string fresca por conexão.

Ambos são paliativos — atualize o zapo quando uma release trouxer um default mais novo.

Depois de reconectar

Parte do estado é escopado à conexão e precisa ser reestabelecido após uma reconexão bem-sucedida:

Assinaturas de presença — faça subscribe() novamente em qualquer contato que você estava observando (Presença).
Atualizações ao vivo de newsletter — faça subscribeLiveUpdates() novamente se você depende delas.

O estado persistido (credenciais, sessões do Signal, app-state) é restaurado da store automaticamente — você não pareia novamente em uma reconexão normal.

Encerramento gracioso

Chame disconnect() para um encerramento limpo que mantém as credenciais, para que você possa retomar mais tarde:

process.on('SIGINT', async () => {
  await client.disconnect()
  process.exit(0)
})

Isso descarrega os dados pendentes de write-behind e fecha o socket sem desvincular o dispositivo.

Primeiros passos

Conceitos

Guias

Plugins

Referência

Avançado

Engenharia reversa

Camadas internas de recuperação

Ciclo de vida da conexão

O evento connection

Um loop de reconexão com backoff

Recuperando de `client_too_old` (HTTP 405)

Depois de reconectar

Encerramento gracioso

​Camadas internas de recuperação

​Ciclo de vida da conexão

​O evento connection

​Um loop de reconexão com backoff

​Recuperando de client_too_old (HTTP 405)

​Depois de reconectar

​Encerramento gracioso

Camadas internas de recuperação

Ciclo de vida da conexão

O evento connection

Um loop de reconexão com backoff

Recuperando de `client_too_old` (HTTP 405)

Depois de reconectar

Encerramento gracioso