Recebendo mensagens

As mensagens recebidas chegam no evento message como um WaIncomingMessageEvent.

import type { WaIncomingMessageEvent } from 'zapo-js'

client.on('message', (event: WaIncomingMessageEvent) => {
  // ...
})

O payload do evento

WaIncomingMessageEvent carrega uma key rica (um superset de Proto.IMessageKey) e alguns campos no topo do objeto. Passe o evento (ou apenas sua key) literalmente para responder / editar / reagir / revogar / fixar / manter.

Campo	Tipo	Descrição
`key.remoteJid`	`string`	JID da conversa sem device (grupo ou 1:1) — o segmento `:device` é stripped; o id do device fica exposto em `key.senderDevice`.
`key.id`	`string`	O id (stanza) da mensagem.
`key.fromMe`	`boolean`	Verdadeiro quando a mensagem foi enviada por esta conta.
`key.participant`	`string?`	O autor em grupos / broadcasts (omitido em 1:1).
`key.isGroup` / `key.isBroadcast` / `key.isNewsletter`	`boolean`	Flags de tipo de chat derivadas de `remoteJid`.
`key.remoteJidAlt`	`string?`	O endereçamento alternativo de `remoteJid` (PN se endereçado por LID, ou vice-versa) em chats 1:1.
`key.participantAlt`	`string?`	O endereçamento alternativo de `participant` em chats em grupo.
`key.senderDevice`	`number`	Id do device do remetente; `0` quando o JID de origem não tem segmento `:device`.
`key.senderUsername`	`string?`	Username do remetente quando o servidor o anexa.
`key.recipientJid` / `key.recipientAlt`	`string?`	Seu JID receptor e sua forma alternativa.
`key.serverId`	`number?`	Id da mensagem atribuído pelo servidor para mensagens de newsletter / canal.
`message`	`Proto.IMessage`	O conteúdo descriptografado da mensagem.
`timestampSeconds`	`number?`	Timestamp do servidor (segundos unix).
`expirationSeconds`	`number?`	TTL de disappearing-message que o remetente anexou a esta mensagem, quando presente.
`pushName`	`string?`	O nome de exibição do remetente.

Você também recebe aqui suas próprias mensagens enviadas (sincronização multi-dispositivo), marcadas com key.fromMe === true. Filtre-as se quiser apenas tráfego de entrada.

O evento inteiro (ou event.key) é aceito como target para replies/reactions/revokes/pins/keeps e como editKey para edições — sem precisar remontá-lo.

Extraindo texto

O texto de uma mensagem fica em campos diferentes dependendo do seu tipo. Um pequeno helper cobre os casos comuns:

function extractText(message?: Proto.IMessage | null): string | undefined {
  if (!message) return undefined
  return (
    message.conversation ??
    message.extendedTextMessage?.text ??
    message.imageMessage?.caption ??
    message.videoMessage?.caption ??
    undefined
  )
}

client.on('message', (event) => {
  const text = extractText(event.message)
  if (text) console.log(`${event.pushName}: ${text}`)
})

Identificando o tipo da mensagem

message é uma union protobuf — inspecione qual campo está definido:

client.on('message', (event) => {
  const m = event.message
  if (!m) return

  if (m.conversation || m.extendedTextMessage) console.log('text')
  else if (m.imageMessage) console.log('image')
  else if (m.videoMessage) console.log('video')
  else if (m.audioMessage) console.log('audio')
  else if (m.documentMessage) console.log('document')
  else if (m.stickerMessage) console.log('sticker')
  else if (m.pollCreationMessage) console.log('poll')
  else if (m.locationMessage) console.log('location')
})

Para baixar mídia de uma mensagem de imagem/vídeo/áudio/documento, veja Mídia → baixando.

Enviando recibos

O client.message.sendReceipt marca mensagens como recebidas/lidas/reproduzidas. A forma mais simples recebe o(s) evento(s) diretamente:

client.on('message', async (event) => {
  // marcar como lida
  await client.message.sendReceipt(event, { type: 'read' })
})

Você também pode passar um array de eventos, ou endereçá-lo manualmente por e ids:

await client.message.sendReceipt(chatJid, [id1, id2], { type: 'read' })

Chamadas

Read-only A sinalização de chamadas recebidas aparece como o evento read-only call (WaIncomingCallEvent). O zapo reporta chamadas — ele não inicia, aceita nem rejeita.

client.on('call', (event) => {
  console.log(
    event.type,          // 'offer' | 'accept' | 'terminate' | … | 'unknown'
    event.isVideo ? 'video' : 'voice',
    'from', event.callerPnJid ?? event.callCreatorJid,
    event.groupJid ? `(group ${event.groupJid})` : ''
  )
})

Campos úteis: type (a etapa da sinalização), callId, callCreatorJid / callerPnJid (quem está ligando), isVideo, groupJid (chamadas de grupo) e callerPushName. Não há API para atender uma chamada.

Addons

Addons são complementos criptografados anexados a uma mensagem: reações, votos em enquetes e comentários. Eles aparecem como o evento message_addon.

Descriptografia automática

Os addons são descriptografados e emitidos para você por padrão — basta se inscrever em message_addon:

const client = new WaClient({ store, sessionId: 'default' }, logger)

client.on('message_addon', (event) => {
  console.log('addon:', event)
})

Descriptografia manual

Passe addons: { autoDecrypt: false } para receber o payload criptografado e descriptografar sob demanda a partir do evento da mensagem de origem:

const client = new WaClient({
  store,
  sessionId: 'default',
  addons: { autoDecrypt: false }
}, logger)

client.on('message', async (event) => {
  await client.message.tryDecryptAddon(event)
})

Mensagens de protocolo

Edições, revogações e outras atualizações em nível de protocolo chegam em message_protocol como WaIncomingProtocolMessageEvent (que estende o evento de mensagem com um campo protocolMessage):

client.on('message_protocol', (event) => {
  console.log(event.protocolMessage)
})

Solicitando histórico antigo

O fluxo inicial de pareamento sincroniza uma janela limitada do histórico de mensagens. Para buscar mensagens mais antigas de um chat específico sob demanda, chame client.message.requestHistorySync:

const { messageId } = await client.message.requestHistorySync({
  chatJid,
  oldestMsgId: topMessage.key.id,
  oldestMsgFromMe: topMessage.key.fromMe,
  oldestMsgTimestampMs: topMessage.timestampSeconds * 1000,
  count: 50
})

O método retorna assim que a solicitação é despachada — não quando o chunk chega. O backfill é entregue depois como um evento history_sync_chunk, do mesmo jeito que o histórico inicial. Inscreva-se antes de chamar se precisar reagir a ele:

client.on('history_sync_chunk', (event) => {
  // event.conversations, event.pushnamesCount, event.progress, ...
})

await client.message.requestHistorySync({ chatJid })

Combine oldestMsgId, oldestMsgFromMe e oldestMsgTimestampMs da mensagem mais antiga visível para paginar para trás corretamente. Omita count para deixar o servidor aplicar o padrão (~50).

Recibos (entrada)

Quando outras pessoas leem ou reproduzem suas mensagens, você recebe eventos receipt:

client.on('receipt', (event) => {
  // event.status: 'delivered' | 'read' | 'played' | 'inactive'
  for (const id of event.messageIds) {
    console.log(event.status, 'for', id)
  }
})

event.messageIds é o conjunto completo de stanza ids que este recibo confirma. O WhatsApp agrupa recibos de read/delivery em um único <receipt> carregando um bloco <list><item id=…/> — messageIds espelha o externalIds do wa-web: itens da lista primeiro, depois event.stanzaId anexado por último. Recibos de mensagem única contêm apenas [event.stanzaId].

Eventos receipt ainda expõem stanzaId / chatJid diretamente (eles estendem WaIncomingBaseEvent); a renomeação se aplica somente aos payloads de message, message_addon e message_bot_chunk, que agora usam event.key. O event.stanzaId ainda é o último id do batch — itere messageIds para cobrir o resto.

Primeiros passos

Conceitos

Guias

Plugins

Referência

Avançado

Engenharia reversa

Recebendo mensagens

O payload do evento

Extraindo texto

Identificando o tipo da mensagem

Enviando recibos

Chamadas

Addons

Descriptografia automática

Descriptografia manual

Mensagens de protocolo

Solicitando histórico antigo

Recibos (entrada)

​O payload do evento

​Extraindo texto

​Identificando o tipo da mensagem

​Enviando recibos

​Chamadas

​Addons

​Descriptografia automática

​Descriptografia manual

​Mensagens de protocolo

​Solicitando histórico antigo

​Recibos (entrada)

O payload do evento

Extraindo texto

Identificando o tipo da mensagem

Enviando recibos

Chamadas

Addons

Descriptografia automática

Descriptografia manual

Mensagens de protocolo

Solicitando histórico antigo

Recibos (entrada)