#20594: feat(whatsapp): batch multi-image messages via debouncer
channel: whatsapp-web
size: XS
Cluster:
Messaging Platform Improvements
## Summary
When multiple images are sent in rapid succession on WhatsApp (e.g., photo albums), this PR enables batching them into a single agent turn instead of processing each image separately.
## Problem
Currently, sending 3 images results in 3 separate agent turns. This:
- Increases API costs (3x tokens)
- Loses context between images (agent responds to image 1 before seeing image 2)
- Doesn't match user intent (they meant 'look at these 3 things together')
## Solution
Leverage the existing `debounceMs` config and `MediaPaths` infrastructure (already used by iMessage, Discord, Telegram) for WhatsApp:
1. **Collect media paths** when batching debounced messages
2. **Pass `MediaPaths`/`MediaTypes`** arrays to the agent context
3. **Backwards compatible** - default `debounceMs` remains 0 (disabled)
## Usage
Enable with config:
```yaml
channels:
whatsapp:
debounceMs: 1500 # 1.5 second window for batching
```
## Changes
- `src/web/inbound/types.ts`: Add `mediaPaths`, `mediaTypes`, `mediaFileNames` to `WebInboundMessage`
- `src/web/inbound/monitor.ts`: Collect all media in `onFlush` when batching
- `src/web/auto-reply/monitor/process-message.ts`: Pass `MediaPaths`/`MediaTypes`/`MediaUrls` to context
## Testing
- Build passes ✅
- Follows existing pattern from iMessage/Discord/Telegram implementations
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR enables WhatsApp to batch multiple images sent in rapid succession into a single agent turn, leveraging the existing `debounceMs` config and `MediaPaths` infrastructure already used by iMessage, Discord, and Telegram.
**Key changes:**
- Added `mediaPaths`, `mediaTypes`, and `mediaFileNames` arrays to `WebInboundMessage` type
- Modified `onFlush` handler in `monitor.ts` to collect all media from batched messages
- Updated `process-message.ts` to pass batched media arrays (`MediaPaths`, `MediaTypes`, `MediaUrls`) to agent context
**Implementation details:**
- Uses `> 0` check (fixed in commit 22ca7ef) to ensure single media items aren't lost, matching Discord/iMessage/Telegram pattern
- Sets `MediaUrls` to `mediaPaths` for local file paths, consistent with other channels
- Backwards compatible - default `debounceMs` remains 0 (disabled)
The implementation correctly follows established patterns from other channels and addresses the issue raised in previous review comments.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- The implementation follows established patterns from Discord, iMessage, and Telegram channels. The previously identified issue with `> 1` vs `> 0` comparison has been fixed in commit 22ca7ef. The changes are minimal, well-scoped, and backwards compatible (disabled by default). The code correctly batches media paths, types, and filenames when multiple messages are debounced.
- No files require special attention
<sub>Last reviewed commit: 22ca7ef</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#15467: feat(messages): add debounceMedia option for inbound debouncing
by tangcruz · 2026-02-13
81.4%
#21309: feat(telegram): support outbound media groups (albums) via sendMedi...
by smysle · 2026-02-19
76.2%
#23148: fix: forward mediaLocalRoots in whatsapp plugin sendMedia
by MunemHashmi · 2026-02-22
75.4%
#9606: fix: pass fileName to WhatsApp document messages
by AytuncYildizli · 2026-02-05
75.2%
#22290: Fix WhatsApp reply quoted-media audio transcription resolution
by apollo-ex · 2026-02-21
75.0%
#19303: Fix WhatsApp internal error leakage + cron.run timeout defaults
by koala73 · 2026-02-17
73.8%
#8705: feat(whatsapp): add viewOnce support for ephemeral media
by ndohuu · 2026-02-04
73.7%
#22143: Fix memory leak in WhatsApp channel reconnection loop
by lancejames221b · 2026-02-20
73.3%
#21881: fix(whatsapp): pass user-provided fileName through document send pipe…
by saakshigupta2002 · 2026-02-20
72.9%
#4390: fix(whatsapp): allow media from allowlisted groups without groupAllow…
by Sarang19114 · 2026-01-30
72.8%