feat(events): expand the message payload and fix silently dropped context

Author: zeative

docs/content/events.mdx

@@ -86,7 +86,26 @@ These deliver a rich [message context](#the-message-context) object — the same
 | `edit` | `EditPayload` | A previously sent message was edited. `{ key, newContent, editedAt, sender }`. |
 | `delete` | `DeletePayload` | A message was deleted. `{ key, deletedFor: 'everyone' \| 'me', sender, timestamp }`. |
 | `reaction` | `ReactionPayload` | Someone reacted to (or un-reacted from) a message. `{ key, emoji, sender, timestamp }`. `emoji` is `null` when the reaction is removed. |
-| `poll-vote` | `PollVotePayload` | A poll vote was cast/changed. `{ pollKey, selectedOptions, voter, timestamp }`. |
+| `poll-vote` | `PollVotePayload` | A poll vote was cast/changed. `{ pollKey, selectedOptions, options(), voter, timestamp }`. |
+
+#### Reading a poll vote
+
+WhatsApp does not send the option text — it sends the **SHA-256 hash** of each option the voter
+picked. `selectedOptions` holds those raw hashes; `options()` looks up the original poll and turns
+them back into readable text:
+
+```ts
+client.on('poll-vote', async (vote) => {
+  const picked = await vote.options()   // ['Nasi Goreng']
+  console.log(`${vote.voter.jid} memilih ${picked.join(', ')}`)
+})
+```
+
+<Callout type="warn">
+`options()` needs the original poll message in the [message store](/storage). If the poll was created
+before your bot started — or you run without a persistent store — it resolves to an empty array. The
+raw hashes in `selectedOptions` are always available.
+</Callout>
 
 ### Interactive replies
 
@@ -279,6 +298,13 @@ client.on('message', async (msg) => {
 | `senderLid` | `string \| null` | The sender's LID (linked-device identifier), if known. Keeps the raw LID even after `senderId` is resolved to PN. |
 | `senderName` | `string \| null` | The sender's WhatsApp push name. |
 | `senderUsername` | `string \| null` | The sender's WhatsApp username (`@handle`), without the `@`. `null` unless WhatsApp sends one — mostly group messages from LID-only senders. |
+| `isOffline` | `boolean` | `true` for a backlog message replayed after a reconnect. Guard on this so the bot does not answer old messages twice. |
+| `forwardCount` | `number` | Forward hops. `>= 5` is WhatsApp's "forwarded many times". |
+| `ephemeralDuration` | `number \| null` | The chat's disappearing timer in seconds. |
+| `addressingMode` | `'pn' \| 'lid'` | How WhatsApp addressed the message. |
+| `mentionedGroups` | `string[]` | Groups tagged via a community `@group` mention. |
+| `ad` | `AdAttribution?` | Meta ad attribution, on the first message of a Click-to-WhatsApp chat only. |
+| `business` | `BusinessInfo?` | Verified business name, for verified business senders only. |
 | `senderDevice` | `SenderDevice` | `'android' \| 'ios' \| 'web' \| 'desktop' \| 'unknown'` — detected from the JID's device suffix. |
 | `timestamp` | `number` | Message time in epoch **milliseconds**. |
 

docs/content/message-payload.mdx

@@ -3,6 +3,8 @@ title: Message Payload (MessageContext)
 description: Every field of the inbound message object zaileys passes to your handlers — where each value comes from, what it means, and how to use it.
 ---
 
+import { Callout } from 'nextra/components'
+
 # Message Payload (`MessageContext`)
 
 Every inbound message handler receives a single **`MessageContext`** object. It is decoded by zaileys from the raw Baileys `WAMessage` into a flat, predictable shape: IDs are normalized, LIDs are resolved to phone numbers where possible, and the heavy parts (group name, replied message, media bytes) are exposed as **lazy functions** so nothing is fetched until you ask for it.
@@ -56,6 +58,13 @@ So plain fields are cheap to read; the function fields do real work (network/asy
 | `senderLid` | `string \| null` | `key.participantAlt` / `remoteJidAlt` ending in `@lid` | The sender's LID, when WhatsApp exposes one. `null` if not available. |
 | `senderName` | `string \| null` | `message.pushName` | Display/push name. Can be `null` or spoofed — don't use for authz. |
 | `senderUsername` | `string \| null` | `key.participantUsername` / `remoteJidUsername` | The sender's WhatsApp username (the `@handle`), without the `@`. `null` unless WhatsApp sends one — see the note below. |
+| `isOffline` | `boolean` | `messages.upsert` type `append` | **`true` for a backlog message replayed after a reconnect.** Skip these so your bot doesn't answer hours-old messages twice. |
+| `forwardCount` | `number` | `contextInfo.forwardingScore` | How many hops the message has been forwarded. `0` = not forwarded, `>= 5` = WhatsApp's "forwarded many times". |
+| `ephemeralDuration` | `number \| null` | `contextInfo.expiration` | The chat's disappearing timer **in seconds**, or `null` when messages are kept. |
+| `addressingMode` | `'pn' \| 'lid'` | `key.addressingMode` | Whether WhatsApp addressed this message by phone number or by LID. Useful when debugging identity resolution. |
+| `mentionedGroups` | `string[]` | `contextInfo.groupMentions` | JIDs of groups tagged in the message (community `@group` mentions). |
+| `ad` | `AdAttribution \| undefined` | `contextInfo.externalAdReply` | Present **only** on the first message of a chat opened from a Meta ad. |
+| `business` | `BusinessInfo \| undefined` | `verifiedBizName` | Present **only** when the sender is a verified WhatsApp Business account. |
 | `senderDevice` | `SenderDevice` | Parsed from the sender's device jid | Which client app sent it: `android` · `ios` · `web` · `desktop` · `unknown`. |
 | `isFromMe` | `boolean` | `key.fromMe === true` | `true` if your own account sent it (echo of your sends, other-device activity). |
 | `isGroup` | `boolean` | `remoteJid` is a group jid | Branch group vs DM logic. |
@@ -156,6 +165,11 @@ Present only for messages that carry media or structured content. The shape depe
 | `fileName` | `string \| null` | Original name (documents). |
 | `fileSize` | `number \| null` | Bytes, when WhatsApp provides it. |
 | `ptt` | `boolean` | `true` for a voice note (push-to-talk audio). |
+| `duration` | `number \| null` | Playback length in **seconds** (audio and video). |
+| `width` / `height` | `number \| null` | Pixel dimensions (image, video, sticker). |
+| `pages` | `number \| null` | Page count (documents). |
+| `isAnimated` | `boolean` | `true` for an animated sticker or a GIF-playback video. |
+| `thumbnail` | `Buffer \| null` | Inline JPEG preview when WhatsApp sent one. |
 | `buffer()` | `Promise<Buffer>` | Downloads the full media into memory. |
 | `stream()` | `Promise<Readable>` | Streams the media (for large files). |
 
@@ -168,6 +182,21 @@ client.on('image', async (ctx) => {
 })
 ```
 
+The metadata fields arrive **with the message**, before any download. Use them to decide whether a
+download is worth it at all:
+
+```ts
+client.on('audio', async (ctx) => {
+  if (ctx.media?.type !== 'audio') return
+  if ((ctx.media.duration ?? 0) > 300) {
+    return ctx.reply('Voice note terlalu panjang, maksimal 5 menit.')
+  }
+  const buf = await ctx.media.buffer()   // only now do we pay for the download
+})
+```
+
+`thumbnail` lets you show a preview without downloading the original at all.
+
 ### Structured media (no download)
 
 Other `chatType`s surface a typed `media` describing the content (no `buffer()`/`stream()`):
@@ -178,6 +207,47 @@ Each carries the fields relevant to it — e.g. `location` has `latitude`/`longi
 
 ---
 
+## `ad` — where a lead came from
+
+When someone taps a **Click-to-WhatsApp** ad on Facebook or Instagram, WhatsApp attaches the ad's
+attribution to the **first message** of that chat. Later messages in the same chat do not carry it.
+
+| Field | Type | Notes |
+|---|---|---|
+| `clickId` | `string?` | The `ctwaClid` click id — join this against Meta Ads reporting. |
+| `sourceId` | `string?` | The ad's id. |
+| `sourceUrl` | `string?` | Landing URL configured on the ad. |
+| `sourceApp` | `string?` | Which surface the ad ran on, e.g. `facebook`, `instagram`. |
+| `sourceType` | `string?` | Ad format as WhatsApp reports it. |
+| `title` / `body` | `string?` | The ad's headline and text. |
+| `thumbnailUrl` | `string?` | Ad creative preview. |
+| `ref` | `string?` | Campaign reference you set on the ad. |
+
+```ts
+client.on('message', async (ctx) => {
+  if (!ctx.ad) return
+  await saveLead({ from: ctx.senderId, campaign: ctx.ad.ref, clickId: ctx.ad.clickId })
+  await ctx.reply(`Halo! Kamu datang dari iklan "${ctx.ad.title}". Ada yang bisa dibantu?`)
+})
+```
+
+<Callout type="warn">
+This is built from WhatsApp's protocol definition but has **not been verified against a live ad click**
+— we have no Click-to-WhatsApp campaign to test with. The field names are correct; report an issue if a
+real ad message shapes differently.
+</Callout>
+
+## `business` — verified business senders
+
+| Field | Type | Notes |
+|---|---|---|
+| `verifiedName` | `string` | The WhatsApp-verified business name. |
+
+Present only when WhatsApp itself verified the sender. Unlike `senderName` (a push name anyone can
+set to anything) this cannot be spoofed, so prefer it when you display or log who you are talking to.
+
+---
+
 ## `chatType` values
 
 ```
@@ -227,7 +297,11 @@ A few values come from your `Client` config rather than the raw message:
 - **`senderId` is a phone-number jid** (`@s.whatsapp.net`), resolved from LID when possible; `senderLid` holds the `@lid` form when present.
 - **Methods are lazy & mostly async.** `roomName()`, `replied()`, `media.buffer()`, `citation.*` do real work — `await` them; they show as `[Function]` when you log the object.
 - **`roomId` follows the conversation, not the direction** — safe as a reply target for both inbound and your own (`isFromMe`) messages.
-- **`isSpam` is reserved** and always `false` today.
+- **`isSpam` is reserved** and always `false` today. Use `forwardCount >= 5` for chain-message detection.
+- **Answer only live messages.** After a reconnect WhatsApp replays everything you missed. Guard with
+  `if (ctx.isOffline) return` unless you deliberately want to process the backlog.
+- **Mirror the disappearing timer on replies.** `ctx.reply()` does not inherit it — pass
+  `ctx.ephemeralDuration` to `.disappearing()` yourself, or your answer outlives the thread it belongs to.
 - **`senderUsername` is usually `null` — WhatsApp sends the phone number _or_ the username, never
   both.** A username is the fallback handle for a sender whose number you cannot see, so it stays
   `null` for anyone whose phone number your account already knows (which is most people). It arrives

src/events/context.ts

@@ -46,6 +46,16 @@ export interface MediaAttachment {
   fileName: string | null
   fileSize: number | null
   ptt: boolean
+  /** Playback length in seconds, for audio and video. */
+  duration: number | null
+  width: number | null
+  height: number | null
+  /** Page count, for documents. */
+  pages: number | null
+  /** `true` for an animated sticker or a GIF-playback video. */
+  isAnimated: boolean
+  /** Inline JPEG preview, when WhatsApp sent one. Lets you show a thumbnail without downloading. */
+  thumbnail: Buffer | null
   buffer(): Promise<Buffer>
   stream(): Promise<Readable>
 }
@@ -206,6 +216,27 @@ export type ContextMedia =
   | InteractiveMedia
   | TemplateMedia
 
+/** Attribution for a chat that started from a Meta ad (Click-to-WhatsApp). */
+export interface AdAttribution {
+  /** The click id to join against Meta Ads reporting. */
+  clickId?: string
+  sourceId?: string
+  sourceUrl?: string
+  /** Which Meta surface the ad ran on, e.g. `facebook`, `instagram`. */
+  sourceApp?: string
+  sourceType?: string
+  title?: string
+  body?: string
+  thumbnailUrl?: string
+  /** Campaign reference you set on the ad. */
+  ref?: string
+}
+
+export interface BusinessInfo {
+  /** WhatsApp-verified business name. Unlike `senderName` this cannot be set by the sender. */
+  verifiedName: string
+}
+
 export interface MessageContext {
   uniqueId: string
   staticId: string
@@ -231,6 +262,20 @@ export interface MessageContext {
   isViewOnce: boolean
   isEphemeral: boolean
   isForwarded: boolean
+  /** `true` for a backlog message replayed after a reconnect. Skip these to avoid answering twice. */
+  isOffline: boolean
+  /** How many hops this message has been forwarded. `>= 5` is WhatsApp's "forwarded many times". */
+  forwardCount: number
+  /** The chat's disappearing timer in seconds, or `null` when messages are kept. */
+  ephemeralDuration: number | null
+  /** Whether WhatsApp addressed this message by phone number or by LID. */
+  addressingMode: 'pn' | 'lid'
+  /** JIDs of groups tagged in the message (community `@group` mentions). */
+  mentionedGroups: string[]
+  /** Present only on the first message of a chat opened from a Meta ad. */
+  ad?: AdAttribution
+  /** Present only when the sender is a verified WhatsApp Business account. */
+  business?: BusinessInfo
   isQuestion: boolean
   isPrefix: boolean
   isTagMe: boolean
@@ -281,6 +326,13 @@ export interface BuildContextInput {
   isForwarded: boolean
   isBroadcast: boolean
   isNewsletter: boolean
+  isOffline?: boolean
+  forwardCount?: number
+  ephemeralDuration?: number | null
+  addressingMode?: 'pn' | 'lid'
+  mentionedGroups?: string[]
+  ad?: AdAttribution
+  business?: BusinessInfo
   prefixes: string[]
   citationConfig?: CitationConfig
   lidMap?: Map<string, string>
@@ -458,6 +510,13 @@ export const buildMessageContext = (input: BuildContextInput): MessageContext =>
     isViewOnce: input.isViewOnce,
     isEphemeral: input.isEphemeral,
     isForwarded: input.isForwarded,
+    isOffline: input.isOffline === true,
+    forwardCount: input.forwardCount ?? 0,
+    ephemeralDuration: input.ephemeralDuration ?? null,
+    addressingMode: input.addressingMode ?? 'pn',
+    mentionedGroups: input.mentionedGroups ?? [],
+    ...(input.ad !== undefined ? { ad: input.ad } : {}),
+    ...(input.business !== undefined ? { business: input.business } : {}),
     isQuestion: isQuestionOf(input.text),
     isPrefix: isPrefixOf(input.text, input.prefixes),
     isTagMe: isTagMeOf(input.selfJid, input.mentions),