Enviando mensagens

Todo o conteúdo de saída passa por um único método:

client.message.send(to, content, options?): Promise<WaMessagePublishResult>

to — o do destinatário (5511999999999@s.whatsapp.net, um grupo ...@g.us, etc.). Veja Helpers de JID para construí-los.
content — uma string, um objeto de conteúdo tipado ou um Proto.IMessage bruto.
options — citação, menções, encaminhamento, visualização única, edições e mais.

A promise resolve para um WaMessagePublishResult assim que o servidor envia o ack:

const result = await client.message.send(jid, 'Hello!')
console.log(result.id) // o id da mensagem (id da stanza)

Texto simples

O conteúdo mais simples é uma string:

await client.message.send(jid, 'Hello from zapo!')

Para mais controle, use a forma de objeto de texto — ela permite anexar context info e ajustar as prévias de link:

await client.message.send(jid, {
  type: 'text',
  text: 'Check this out: https://example.com',
  linkPreview: true // busca a prévia automaticamente
})

Respondendo (citação)

Passe o evento da mensagem original (ou uma referência) como options.quote:

client.on('message', async (event) => {
  await client.message.send(event.key.remoteJid, 'Replying to you', {
    quote: event
  })
})

A citação é renderizada como um balão de resposta referenciando a mensagem original.

Menções

options.mentions é uma lista de JIDs para marcar. Inclua o texto @número correspondente no corpo para que o WhatsApp renderize a menção:

await client.message.send(groupJid, {
  type: 'text',
  text: 'Hey @5511999999999, welcome!'
}, {
  mentions: ['5511999999999@s.whatsapp.net']
})

Prévias de link

O comportamento da prévia de link é controlado por mensagem através do campo linkPreview do objeto de texto:

Valor	Comportamento
`undefined`	Segue o padrão global de `linkPreview`.
`false`	Desabilita a prévia.
`true`	Força a busca automática da prévia.
objeto	Pula a busca e usa os campos de prévia fornecidos diretamente.

// Forneça sua própria prévia em vez de buscar
await client.message.send(jid, {
  type: 'text',
  text: 'https://example.com',
  linkPreview: { title: 'Example', description: 'My custom preview' }
})

Configure o fetcher padrão globalmente com a opção linkPreview do client.

Encaminhamento

Defina options.forward para marcar uma mensagem como encaminhada:

await client.message.send(jid, 'Forwarded text', { forward: true })
// ou com uma pontuação de encaminhamento frequente
await client.message.send(jid, content, { forward: { score: 4 } })

Referência de opções de envio

WaSendMessageOptions (terceiro argumento) inclui:

Opção	Tipo	Propósito
`quote`	`WaIncomingMessageEvent \| WaQuoteRef \| WaMessageKey`	Responder a uma mensagem — passe o evento literalmente, sua `key`, ou um `WaQuoteRef`.
`mentions`	`string[]`	JIDs para mencionar.
`forward`	`boolean \| { score }`	Marcar como encaminhada.
`viewOnce`	`boolean`	Empacotar imagem/vídeo/áudio como visualização única.
`editKey`	`WaMessageKey \| WaSendEditKey \| WaMessageRef`	Editar uma mensagem enviada anteriormente (veja interativas).
`expirationSeconds`	`number`	TTL de disappearing-message para esta mensagem. Vence sobre `contextInfo.expirationSeconds` e sobre o injeção automática de group-ephemeral (a última é curto-circuitada assim que este campo é definido — mesmo `0`).
`disableGroupEphemeralAutoInject`	`boolean`	Pula a injeção automática do ephemeral-setting em envios de grupo (`expiration` e `disappearingMode` do cache de group metadata). Sem efeito em 1:1. Redundante quando `expirationSeconds` está definido.
`disableDirectEphemeralAutoInject`	`boolean`	Pula a injeção automática do ephemeral-setting em envios 1:1 (`expiration`, `ephemeralSettingTimestamp` e `disappearingMode` do cache `chatMetadata`) — também pula a lookup no cache. Sem efeito em grupos. Redundante quando `expirationSeconds` está definido.
`contextInfo`	`WaSendContextInfo`	Context info bruto (avançado).
`id`	`string`	Usar um id de mensagem específico.
`ackTimeoutMs` / `maxAttempts` / `retryDelayMs`	`number`	Ajuste de retentativa por envio.

Para enviar uma única mensagem sem expiração para um grupo com disappearing-mode ligado, prefira disableGroupEphemeralAutoInject: true em vez de expirationSeconds: 0 — o último ainda grava expiration=0 no contextInfo de saída. Mesma história para disableDirectEphemeralAutoInject em chats 1:1.

Enviando pra um username

Um handle de username (@alice) não é um JID endereçável sozinho. Resolva pro LID da conta com client.profile.resolveUsername primeiro, e depois envie pra esse JID — a API de envio recebe o JID exatamente como qualquer outro destinatário 1:1. resolveUsername retorna uma union discriminada em que você tem que switchar. Cada caso tem um próximo passo:

const result = await client.profile.resolveUsername({ username: '@alice' })

switch (result.status) {
  case 'found':
    // result.jid é o LID (@lid) pra endereçar; result.pnJid é a forma phone-jid
    // quando o servidor a conhece, e result.isBusiness sinaliza uma conta business.
    // result.username é o handle canônico que o servidor ecoa de volta.
    await client.message.send(result.jid, 'oi')
    break

  case 'key-required': {
    // O servidor segurou o JID até a chave de recuperação de 4 dígitos ser
    // fornecida. Peça ao usuário (fora de banda — a UI do WhatsApp mostra
    // como "@handle:1234") e retente com a chave. Um input pontual '@user:1234'
    // também funciona: resolveUsername parseia o sufixo ':1234' pra usernameKey.
    const usernameKey = await askUserForFourDigitKey() // sua UI
    const retry = await client.profile.resolveUsername({ username: '@alice', usernameKey })
    if (retry.status === 'found') await client.message.send(retry.jid, 'oi')
    else if (retry.status === 'key-required') console.log('chave errada')
    else console.log('handle inexistente')
    break
  }

  case 'not-found':
    // Terminal — o handle não está registrado no WhatsApp. Nenhum retry recupera.
    console.log('handle inexistente')
    break
}

resolveUsername lança antes de qualquer round-trip quando o handle ou a chave falham na validação local (caracteres inválidos, comprimento errado, palavra reservada, chave que não tem exatamente 4 dígitos) — então uma chamada que retorna passou nas regras locais, e o status reflete o resultado do servidor.

A union de conteúdo

content aceita qualquer WaSendMessageContent. As variantes tipadas estão documentadas ao longo destes guias:

Mídia

Imagens, vídeo, áudio, documentos, figurinhas.

Enquetes e reações

Enquetes, votos, reações, fixações, edições, revogações, eventos.

Você sempre pode recorrer a um Proto.IMessage bruto para qualquer coisa não coberta por um builder tipado:

import { proto } from 'zapo-js'

await client.message.send(jid, {
  conversation: 'Raw protobuf message'
})

Tipos de conteúdo sem um builder tipado ainda — localizações, cartões de contato vCard e cards de pagamento Business PIX / review-and-pay — estão documentados em Envios proto brutos. O conjunto completo de campos Proto.IMessage reconhecidos (localização, localização ao vivo, contatos, convite de grupo, produto, pedido, …) está na referência de tipos de mensagem.

Primeiros passos

Conceitos

Guias

Plugins

Referência

Avançado

Engenharia reversa

Enviando mensagens

Texto simples

Respondendo (citação)

Menções

Prévias de link

Encaminhamento

Referência de opções de envio

Enviando pra um username

A union de conteúdo

Mídia

Enquetes e reações

​Texto simples

​Respondendo (citação)

​Menções

​Prévias de link

​Encaminhamento

​Referência de opções de envio

​Enviando pra um username

​A union de conteúdo

Mídia

Enquetes e reações

Texto simples

Respondendo (citação)

Menções

Prévias de link

Encaminhamento

Referência de opções de envio

Enviando pra um username

A union de conteúdo