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, ou uma mensagem hosted/bot que o servidor não conseguiu fazer fanout. Não há nada para decifrar, mas a chegada em si ainda é informação útil (audit logs, linhas “esta mensagem não está mais disponível” na UI). A lib ackeia e emite um evento tipado message_unavailable com discriminador kind:

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

Campo	Tipo	Notas
`kind`	`'view_once' \| 'hosted' \| 'other'`	Qual variante de conteúdo o servidor sinalizou como indisponível.
`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.

Não há payload message — o corpo realmente sumiu (ou nunca foi criptografado para este device).

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.

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`.
`offline_resume`	`WaOfflineResumeEvent`	Progresso da drenagem de mensagens offline pós-conexão.
`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))

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

​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

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