Eventos

O WaClient é um emissor de eventos fortemente tipado. Cada atividade de entrada — mensagens, recibos, mudanças em grupos, presença — é exposta como um evento com um payload tipado.

Plugins podem contribuir com seus próprios eventos tipados; eles aparecem em client.on apenas quando o plugin está no array plugins. Veja o guia de VoIP para um exemplo — seus eventos voip_* ficam disponíveis quando voipPlugin() está instalado.

Escutando

import type { WaIncomingMessageEvent } from 'zapo-js'

client.on('message', (event: WaIncomingMessageEvent) => {
  console.log(event.key.remoteJid, event.message)
})

client.once('auth_paired', ({ credentials }) => {
  console.log('paired', credentials.meJid)
})

const handler = (e) => { /* ... */ }
client.on('receipt', handler)
client.off('receipt', handler) // para de escutar

on, once e off são todos verificados por tipo contra o mapa de eventos — o tipo do payload é inferido a partir do nome do evento, então os listeners têm autocomplete completo.

Auth e conexão

Evento	Payload	Descrição
`auth_qr`	`{ qr, ttlMs }`	Um QR code para renderizar no pareamento.
`auth_pairing_code`	`{ code }`	Um código de pareamento de 8 caracteres foi emitido.
`auth_pairing_required`	`{ forceManual }`	A sessão precisa de entrada de pareamento.
`auth_passkey_required`	`{ hasSigner }`	O servidor está forçando uma passkey Shortcake para linkar. `hasSigner: false` significa que o handshake para até você configurar um signer.
`auth_paired`	`{ credentials }`	O pareamento teve sucesso.
`connection`	`WaConnectionEvent`	Socket aberto ou fechado (veja abaixo).

O evento connection é uma union discriminada por status:

client.on('connection', (event) => {
  if (event.status === 'open') {
    console.log('online; new login?', event.isNewLogin)
  } else {
    console.log('closed:', event.reason, 'logout?', event.isLogout)
  }
})

Veja Reconexão para o padrão de tratamento.

Mensagens

Evento	Payload	Descrição
`message`	`WaIncomingMessageEvent`	Uma stanza `<message>` inbound foi descriptografada.
`message_send`	`WaOutgoingMessageEvent`	Uma mensagem outbound que este client está enviando, com o `Proto.IMessage` descriptografado — a contrapartida simétrica do `message`. Permite que plugins / loggers observem forwards, reações, polls, mídia que a stanza de wire esconde.
`message_addon`	`WaIncomingAddonEvent`	Reações, votos em enquetes, comentários (addons descriptografados).
`message_protocol`	`WaIncomingProtocolMessageEvent`	Mensagens de protocolo (edições, revogações, …).
`message_bot_chunk`	`WaIncomingBotChunkEvent`	Chunks de resposta de bot em stream.
`message_unavailable`	`WaIncomingUnavailableMessageEvent`	Chegou um placeholder sem conteúdo (veja Mensagens indisponíveis).
`receipt`	`WaIncomingReceiptEvent`	Recibos de entrega / leitura / reprodução.

Veja Recebendo mensagens para detalhes do payload e extração de texto.

Mensagens indisponíveis

Algumas stanzas <message> recebidas carregam um marcador <unavailable/> no lugar de um corpo criptografado — uma view-once cujo conteúdo já foi consumido, uma mensagem hosted/bot que o servidor não conseguiu fazer fanout, ou um placeholder de fanout simples que o dispositivo primário ainda pode reenviar. Não há nada para decifrar na stanza em si, mas a chegada é informação útil (audit logs, linha “esta mensagem não está mais disponível” na UI, ou aguardar o resend chegar). A lib ackeia e emite um evento tipado message_unavailable com discriminador kind:

client.on('message_unavailable', (event) => {
  // event.kind: 'view_once' | 'hosted' | 'bot' | 'other'
  console.log('indisponível', event.kind, 'resendRequested?', event.resendRequested,
    'de', event.key.remoteJid, 'id', event.key.id)
})

Campo	Tipo	Notas
`kind`	`'view_once' \| 'hosted' \| 'bot' \| 'other'`	Qual variante o servidor sinalizou. `'other'` é um placeholder de fanout simples — o único kind recuperável.
`resendRequested`	`boolean`	`true` quando a lib enfileirou uma peer request `PLACEHOLDER_MESSAGE_RESEND`; o payload chega depois como evento `message` com o mesmo `key.id`. `false` para os kinds não recuperáveis, mensagens além da janela de idade das AB props, e sessões mobile-primary.
`key`	`WaIncomingMessageKey`	Mesma forma que o evento `message` carrega — armazene ou correlacione como qualquer outro id de mensagem.
`timestampSeconds`	`number?`	Vem do attr `t` da stanza.
`pushName`	`string?`	Nome de exibição do remetente vindo do attr `notify` da stanza.

As requisições de resend são best-effort — como no wa-web, elas não são persistidas, então uma peer request que falha não é retentada. Veja Recebendo mensagens → Recuperando mensagens indisponíveis para os detalhes.

Presença e chat-state

Evento	Payload	Descrição
`presence`	`WaIncomingPresenceEvent`	A presença de um contato mudou (disponível / visto por último).
`chatstate`	`WaIncomingChatstateEvent`	Digitando / gravando / pausado.
`call`	`WaIncomingCallEvent`	Sinalização de chamada de entrada.

Grupos, newsletters e perfis

Evento	Payload	Descrição
`group`	`WaGroupEvent`	Mudanças de criação/assunto/participante/configuração de grupo.
`newsletter`	`WaIncomingNewsletterEvent`	Atividade de newsletter.
`newsletter_message_update`	`WaIncomingNewsletterMessageUpdateEvent`	Edições/reações/atualizações de enquete em mensagens de newsletter.
`business`	`WaBusinessEvent`	Mudanças no perfil business.
`picture`	`WaPictureEvent`	Mudanças de foto de perfil/grupo.
`privacy`	`WaPrivacyAccountSyncResult`	A privacidade da conta foi mudada no primário ou em outro companion — o conjunto inteiro de categorias mais qualquer disallowed list que o servidor reportou. Debounced 1s, então uma rajada de mudanças no celular colapsa em um único refresh. Os valores sempre vêm de uma leitura fresca, nunca do payload da notificação.
`blocklist`	`WaBlocklistResult`	O blocklist da conta depois de um bloqueio/desbloqueio feito em outro device. Mesmo caminho de refetch que `privacy`; o payload é a lista completa, nunca um delta.
`own_username`	`WaOwnUsernameNotificationEvent`	O username da conta foi definido / removido / modificado no primário ou em outro companion. `kind` discrimina a mudança; `username` só é preenchido para `kind: 'set'`.

Estado, histórico e MEX

Evento	Payload	Descrição
`mutation`	`WaAppStateMutationEvent`	Mutation de app-state (silenciar, fixar, arquivar, …) sincronizada de outro dispositivo. Somente inbound; ações outbound deste próprio client aparecem em `mutation_send`.
`mutation_send`	`WaAppStateMutationEvent`	Uma ação de app-state que este client está enviando — a contrapartida outbound do `mutation`, simétrica a como `message_send` faz par com `message`. `event.source` é sempre `'local'`. Otimista: emitido no momento em que a mutation é enfileirada, antes do flush do servidor confirmar.
`history_sync_chunk`	`WaHistorySyncChunkEvent`	Um chunk de histórico de mensagens sincronizado (bootstrap inicial ou backfill via `message.requestHistorySync`). Pulado apenas quando `history.enabled` é explicitamente `false`. O ingest é streamado — o reader proto desce em `conversations` uma mensagem por vez, então o pico de memória do ingest fica plano independentemente do tamanho do chunk. `messagesCount` conta registros escritos, não lidos; um chunk cujo park bounded de mensagens esperando `Conversation.id` estoura falha e fica sem ack (o primário reenvia), em vez de completar com drops silenciosos.
`group_history_bundle`	`WaGroupHistoryBundleEvent`	Um bundle de histórico de grupo que outro membro compartilhou com esta conta depois que ela entrou em um grupo, já baixado, filtrado e persistido. Requer `history.groupBundles: true` — o fetch é opt-in porque um terceiro dispara. Veja Grupos → recebendo.
`offline_resume`	`WaOfflineResumeEvent`	Progresso da drenagem de mensagens offline pós-conexão.
`offline_thread_metadata`	`WaOfflineThreadMetadataEvent`	Manifesto de preview da fila offline (timestamps do último stanza por thread, watermarks de leitura opcionais por thread, contagens opcionais de backlog de status / notificações). Enviado logo antes do flush; sem garantia de chegada. Use `offline_resume` para progresso, nunca este.
`mex_notification`	`WaMexNotificationEvent`	Notificações MEX (GraphQL): nome de usuário, status, mudanças de LID, capping.

Kinds de notificação MEX

WaMexNotificationEvent é uma union discriminada por kind. Toda variante carrega operationName (a operação GraphQL upstream) e errors: readonly WaMexNotificationGraphQlError[] (quaisquer erros GraphQL que o servidor anexou — tipicamente vazio).

`kind`	`operationName`	Campos extras
`username_set`	`UsernameSetNotification`	`lidJid`, `username` — um contato definiu ou mudou o username.
`username_delete`	`UsernameDeleteNotification`	`lidJid`, `displayName: string \| null` — username removido (`null` indica que o servidor omitiu o nome de fallback).
`username_update_hint`	`UsernameUpdateNotification`	`contactHash` — hint lateral de que algo mudou para um bucket de contato; refetch pelo caminho normal de perfil.
`own_username_sync`	`AccountSyncUsernameNotification`	`ownLidJid`, `username \| null`, `state \| null`, `pin \| null` — seu próprio estado de username sincronizado de outro device. `username` `null` indica que foi removido.
`text_status_update`	`TextStatusUpdateNotification`	`jid`, `text \| null`, `emoji \| null`, `ephemeralDurationSec \| null`, `lastUpdateTime \| null` — o “about”/status de um contato mudou. `text`/`emoji` `null` limpa aquele campo.
`text_status_update_hint`	`TextStatusUpdateNotificationSideSub`	`contactHash` — hint lateral; refetch o status.
`lid_change`	`LidChangeNotification`	`oldLidJid`, `newLidJid` — o LID de um usuário rotacionou. Veja Mudanças de LID.
`message_capping`	`MessageCappingInfoNotification`	`cappingStatus` (`'NONE' \| 'FIRST_WARNING' \| 'SECOND_WARNING' \| 'CAPPED' \| string`), mais opcionais `oteStatus`, `mvStatus`, `totalQuota`, `usedQuota`, `cycleStartTimestamp`, `cycleEndTimestamp`, `serverSentTimestamp` — estado da quota de envio da sua conta.
`unknown`	(o que o servidor enviar)	`data: unknown` — catch-all para um `operationName` sem variante tipada; o `data` bruto do GraphQL é repassado literalmente para você decodificar.

client.on('mex_notification', (event) => {
  switch (event.kind) {
    case 'username_set':
      console.log(`${event.lidJid} agora se chama @${event.username}`)
      break
    case 'text_status_update':
      console.log(`status de ${event.jid}:`, event.text, event.emoji)
      break
    case 'message_capping':
      console.log(`capping ${event.cappingStatus}:`, event.usedQuota, '/', event.totalQuota)
      break
    case 'lid_change':
      console.log('LID rotacionou:', event.oldLidJid, '→', event.newLidJid)
      break
  }
})

Os kinds *_hint (username_update_hint, text_status_update_hint) trazem apenas um contactHash, não o valor novo — o servidor está dizendo “algo mudou para esse bucket” e o client é responsável por refetch pelo caminho normal de perfil / status.

Companion host (mobile-primary)

Emitidos pelo coordinator client.mobile quando uma sessão mobile-primary linka, revoga ou falha ao provisionar um device companion. Os três só disparam em sessão mobile-primary.

Evento	Payload	Descrição
`companion_host_linked`	`{ deviceJid: string, keyIndex: number }`	Um companion linkado com sucesso via `linkCompanion` / `linkCompanionByCode`.
`companion_host_revoked`	`{ deviceJid: string }`	Um companion hospedado foi removido — via `revokeCompanion` / `revokeAllCompanions`, ou dropado durante uma varredura de `reconcileCompanions()` depois que o usuário desvinculou de outra surface.
`companion_host_error`	`Error`	Um passo de link ou de provisioning em background falhou.

Falhas

Evento	Payload	Descrição
`stream_failure`	`WaIncomingFailureEvent`	Uma falha em nível de stream (pode preceder uma desconexão).
`stanza_error`	`WaIncomingErrorStanzaEvent`	Uma stanza de erro do servidor.

Eventos de debug

Uma família de eventos debug_* expõe internals de baixo nível — frames brutos, nodes decodificados, erros de decode, stanzas não tratadas e erros do client. São úteis para depuração de protocolo, mas barulhentos; inscreva-se seletivamente.

client.on('debug_transport_node_in', ({ node }) => console.dir(node, { depth: null }))
client.on('debug_client_error', ({ error }) => console.error(error))

debug_decrypted_payload

O plaintext de cada <enc> descriptografado da stanza, emitido entre o unpad e o proto.Message.decode. Dispara quer o decode dê certo ou não — o que torna o caso de falha observável. Sem esse hook, um payload que descriptografa mas não decodifica (um campo proto que a lib ainda não conhece, um corpo malformado) se perde: decode lança, a stanza é reportada em debug_unhandled_stanza, e os bytes vão junto — enquanto a decriptação já avançou o ratchet, então esse mesmo ciphertext nunca vai decifrar de novo.

Campo	Tipo	Notas
`encIndex`	`number`	Qual `<enc>` da stanza produziu esses bytes, contando de zero. Uma mensagem endereçada a vários dispositivos carrega vários `<enc>` cujos ciphertexts são independentes — atribuir um payload ao índice errado atribui ao remetente errado.
`encType`	`string`	O atributo `type` do `<enc>`: `msg`, `pkmsg`, `skmsg`, …
`plaintext`	`Uint8Array`	O plaintext sem padding. Uma cópia, então mutar não altera a mensagem que a lib então entrega.

client.on('debug_decrypted_payload', ({ encIndex, encType, plaintext }) => {
  fs.appendFileSync('payloads.bin', plaintext)
  console.log('captured', encType, 'idx', encIndex, plaintext.length, 'bytes')
})

Não custa nada quando ninguém está inscrito — a cópia do plaintext só é construída quando existe pelo menos um listener. Útil para gravar tráfego para replay fiel (re-encodar uma mensagem decodada não reproduz os bytes originais), ou decodificar com um protobuf mais novo do que a lib carrega. Um listener que lança é engolido e logado, então um observer buggy não pode envenenar a entrega.

Os eventos de registro mobile (mobile_registration_code, mobile_account_takeover_notice) existem para o caminho de registro mobile e não fazem parte do fluxo companion padrão.

Primeiros passos

Conceitos

Guias

Plugins

Referência

Avançado

Engenharia reversa

Escutando

Auth e conexão

Mensagens

Mensagens indisponíveis

Presença e chat-state

Grupos, newsletters e perfis

Estado, histórico e MEX

Kinds de notificação MEX

Companion host (mobile-primary)

Falhas

Eventos de debug

debug_decrypted_payload

​Escutando

​Auth e conexão

​Mensagens

​Mensagens indisponíveis

​Presença e chat-state

​Grupos, newsletters e perfis

​Estado, histórico e MEX

​Kinds de notificação MEX

​Companion host (mobile-primary)

​Falhas

​Eventos de debug

​debug_decrypted_payload

Escutando

Auth e conexão

Mensagens

Mensagens indisponíveis

Presença e chat-state

Grupos, newsletters e perfis

Estado, histórico e MEX

Kinds de notificação MEX

Companion host (mobile-primary)

Falhas

Eventos de debug

debug_decrypted_payload