openclaw - 💡(How to fix) Fix WhatsApp: coalesce rapid same-sender media/file uploads into one agent turn

Summary

WhatsApp inbound media/file bursts currently arrive as separate messages and can trigger multiple agent runs/replies when a user uploads several images/files at once.

Telegram has first-class album grouping via media_group_id and OpenClaw buffers those with channels.telegram.mediaGroupFlushMs. WhatsApp/Web/Baileys does not appear to expose an equivalent reliable album id in the current channel flow, so the WhatsApp plugin needs its own short same-sender media batching window.

Current behavior

In @openclaw/[email protected], inbound debounce exists (channels.whatsapp.debounceMs / messages.inbound), but media is explicitly excluded from debouncing.

Observed source shape in extensions/whatsapp/src/monitor compiled runtime:

const shouldDebounce = (msg) => {
  if (msg.mediaPath || msg.mediaType) return false;
  if (msg.location) return false;
  if (msg.replyToId || msg.replyToBody) return false;
  return !isControlCommandMessage(msg.body, cfg);
};

The inbound context builder also currently models only one attachment per inbound turn:

const media = toInboundMediaFacts(params.msg.mediaPath || params.msg.mediaUrl ? [{
  path: params.msg.mediaPath,
  url: params.msg.mediaUrl ?? params.msg.mediaPath,
  contentType: params.msg.mediaType
}] : void 0, ...);

So simply allowing the existing text debounce for media would be unsafe unless the inbound message model can preserve all media items.

User-facing problem

If a WhatsApp user sends/uploads multiple files or images in quick succession as one intended request, OpenClaw may process each media message separately and reply multiple times. This is noisy in DMs and especially disruptive in groups.

Proposed behavior

Add a WhatsApp-specific media batching/coalescing path:

• New config, for example:
  • channels.whatsapp.mediaBatchFlushMs (default maybe 0 or 3000)
  • optionally channels.whatsapp.mediaBatchMaxItems (default maybe 10)
• Scope batching by accountId + conversation/chat JID + sender.
• Batch only rapid same-sender media/file messages within the flush window.
• Preserve all original dedupe/read receipt/durable journal entries.
• Dispatch a single agent turn after the flush window.
• Use the latest message id for reply threading/quoting, or document which item is quoted.
• Combine captions/text bodies in order.
• Keep control commands, explicit replies/quotes, and location messages as immediate/special cases unless there is a deliberate product decision otherwise.

Required model/context changes

The WhatsApp inbound message/context should support multi-media fields, for example:

mediaPaths?: string[];
mediaTypes?: string[];
mediaFileNames?: string[];

Then buildWhatsAppInboundContext can pass all items to toInboundMediaFacts(...), while retaining backward compatibility with existing single mediaPath/mediaType.

Acceptance criteria

1. Sending 3 images/files quickly from the same WhatsApp sender results in one agent turn and one reply.
2. The agent receives/has access to all 3 media items, not only the last/first one.
3. Dedupe/read receipts/durable replay remain correct for every original inbound message.
4. Text-only debounce behavior remains unchanged.
5. Telegram mediaGroupFlushMs behavior remains unchanged.

Notes

This is similar in spirit to Telegram album buffering, but should not depend on Telegram-style media_group_id because WhatsApp media bursts are represented differently in the current Baileys channel flow.