Sending messages

All outgoing content goes through a single method:

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

to — the recipient (5511999999999@s.whatsapp.net, a group ...@g.us, etc.). See JID helpers for building these.
content — a string, a typed content object, or a raw Proto.IMessage.
options — quoting, mentions, forwarding, view-once, edits, and more.

The promise resolves to a WaMessagePublishResult once the server acks:

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

Plain text

The simplest content is a string:

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

For more control, use the text object form — it lets you attach context info and tune link previews:

await client.message.send(jid, {
  type: 'text',
  text: 'Check this out: https://example.com',
  linkPreview: true // auto-fetch a preview
})

Replying (quoting)

Pass the original message event (or a reference) as options.quote:

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

The quote is rendered as a reply bubble referencing the original message.

Mentions

options.mentions is a list of JIDs to tag. Include the matching @number text in the body so WhatsApp renders the mention:

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

Link previews

Link-preview behavior is controlled per message via the text object’s linkPreview field:

Value	Behavior
`undefined`	Follow the global `linkPreview` default.
`false`	Disable the preview.
`true`	Force auto-fetch of the preview.
object	Skip the fetch and use the provided preview fields directly.

// Provide your own preview instead of fetching
await client.message.send(jid, {
  type: 'text',
  text: 'https://example.com',
  linkPreview: { title: 'Example', description: 'My custom preview' }
})

Configure the default fetcher globally with the linkPreview client option.

Forwarding

Set options.forward to mark a message as forwarded:

await client.message.send(jid, 'Forwarded text', { forward: true })
// or with a frequently-forwarded score
await client.message.send(jid, content, { forward: { score: 4 } })

Send options reference

WaSendMessageOptions (third argument) includes:

Option	Type	Purpose
`quote`	`WaIncomingMessageEvent \| WaQuoteRef \| WaMessageKey`	Reply to a message — pass the event verbatim, its `key`, or a `WaQuoteRef`.
`mentions`	`string[]`	JIDs to mention.
`forward`	`boolean \| { score }`	Mark as forwarded.
`viewOnce`	`boolean`	Wrap image/video/audio as view-once.
`editKey`	`WaMessageKey \| WaSendEditKey \| WaMessageRef`	Edit a previously sent message (see interactive).
`expirationSeconds`	`number`	Disappearing-message TTL for this message. Wins over `contextInfo.expirationSeconds` and over the automatic group-ephemeral inject (the latter is short-circuited as soon as this is defined — even `0`).
`disableGroupEphemeralAutoInject`	`boolean`	Skip the automatic ephemeral-setting injection on group sends (`expiration` and `disappearingMode` from the group metadata cache). No effect on 1:1. Redundant when `expirationSeconds` is set.
`disableDirectEphemeralAutoInject`	`boolean`	Skip the automatic ephemeral-setting injection on 1:1 sends (`expiration`, `ephemeralSettingTimestamp` and `disappearingMode` from the `chatMetadata` cache) — also skips the cache lookup. No effect on groups. Redundant when `expirationSeconds` is set.
`contextInfo`	`WaSendContextInfo`	Raw context info (advanced).
`id`	`string`	Use a specific message id.
`ackTimeoutMs` / `maxAttempts` / `retryDelayMs`	`number`	Per-send retry tuning.

To send a single message with no expiration into a group with disappearing-mode on, prefer disableGroupEphemeralAutoInject: true over expirationSeconds: 0 — the latter still writes expiration=0 into the outgoing contextInfo. Same story for disableDirectEphemeralAutoInject in 1:1 chats.

Sending to a username

A username handle (@alice) is not an addressable JID on its own. Resolve it to the account’s LID with client.profile.resolveUsername first, then send to that JID — the send API takes the JID exactly like any other 1:1 recipient. resolveUsername returns a discriminated union you have to switch on. Every case has a next step:

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

switch (result.status) {
  case 'found':
    // result.jid is the LID (@lid) to address; result.pnJid is the phone-jid
    // form when the server knows it, and result.isBusiness flags a business
    // account. result.username is the canonical handle the server echoes back.
    await client.message.send(result.jid, 'hi')
    break

  case 'key-required': {
    // The server withheld the JID until the 4-digit recovery key is supplied.
    // Ask the user for it (out of band — WhatsApp UI shows it as "@handle:1234")
    // and retry with the key. A one-off '@user:1234' input works too:
    // resolveUsername parses the ':1234' suffix into usernameKey for you.
    const usernameKey = await askUserForFourDigitKey() // your UI
    const retry = await client.profile.resolveUsername({ username: '@alice', usernameKey })
    if (retry.status === 'found') await client.message.send(retry.jid, 'hi')
    else if (retry.status === 'key-required') console.log('wrong key')
    else console.log('no such handle')
    break
  }

  case 'not-found':
    // Terminal — the handle is not registered on WhatsApp. No retry recovers it.
    console.log('no such handle')
    break
}

resolveUsername throws before any round-trip when the handle or the key fails local validation (bad characters, wrong length, reserved word, key that is not exactly 4 digits) — so a call that returns has passed local rules and the status reflects the server-side outcome.

The content union

content accepts any WaSendMessageContent. The typed variants are documented across these guides:

Media

Images, video, audio, documents, stickers.

Polls & reactions

Polls, votes, reactions, pins, edits, revokes, events.

You can always drop down to a raw Proto.IMessage for anything not covered by a typed builder:

import { proto } from 'zapo-js'

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

Content types without a typed builder yet — locations, contact vCards, and Business PIX / review-and-pay payment cards — are documented in Raw proto sends. The full set of recognized Proto.IMessage fields (location, live location, contacts, group invite, product, order, …) is listed in the message types reference.

Getting started

Core concepts

Guides

Plugins

Reference

Advanced

Reverse engineering

Sending messages

Plain text

Replying (quoting)

Mentions

Link previews

Forwarding

Send options reference

Sending to a username

The content union

Media

Polls & reactions

​Plain text

​Replying (quoting)

​Mentions

​Link previews

​Forwarding

​Send options reference

​Sending to a username

​The content union

Media

Polls & reactions

Plain text

Replying (quoting)

Mentions

Link previews

Forwarding

Send options reference

Sending to a username

The content union