> ## Documentation Index
> Fetch the complete documentation index at: https://zapo.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos

> Referência de todos os eventos do WaClient: mensagens, recibos, grupos, sincronização de histórico, mutações de app-state e falhas.

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.

<Note>
  [Plugins](/pt-br/concepts/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](/pt-br/guides/voip) para um exemplo — seus eventos `voip_*` ficam disponíveis quando `voipPlugin()` está instalado.
</Note>

<h2 id="listening">
  Escutando
</h2>

```ts theme={null}
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.

<h2 id="auth--connection">
  Auth e conexão
</h2>

| 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](/pt-br/concepts/authentication#passkey-gated-linking-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`:

```ts theme={null}
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](/pt-br/guides/reconnection) para o padrão de tratamento.

<h2 id="messages">
  Mensagens
</h2>

| 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](#unavailable-messages)).                                                                                                                                                 |
| `receipt`             | `WaIncomingReceiptEvent`            | Recibos de entrega / leitura / reprodução.                                                                                                                                                                                                  |

Veja [Recebendo mensagens](/pt-br/guides/receiving-messages) para detalhes do payload e extração de texto.

<h3 id="unavailable-messages">
  Mensagens indisponíveis
</h3>

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`:

```ts theme={null}
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).

<h2 id="presence--chat-state">
  Presença e chat-state
</h2>

| 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.                              |

<h2 id="groups-newsletters--profiles">
  Grupos, newsletters e perfis
</h2>

| 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.                                   |

<h2 id="state-history--mex">
  Estado, histórico e MEX
</h2>

| 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.                                                                                                                                                                                                                  |

<h3 id="mex-notification-kinds">
  Kinds de notificação MEX
</h3>

`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](/pt-br/concepts/identities#lid-changes).                                                                                                                                             |
| `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.                                                                                                                     |

```ts theme={null}
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
  }
})
```

<Note>
  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.
</Note>

<h2 id="companion-host-mobile-primary">
  Companion host (mobile-primary)
</h2>

Emitidos pelo coordinator [`client.mobile`](/pt-br/concepts/mobile#hosting-companion-devices) 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.                                                                                                                                           |

<h2 id="failures">
  Falhas
</h2>

| 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.                              |

<h2 id="debug-events">
  Eventos de debug
</h2>

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.

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

<Note>
  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.
</Note>