Summary

• Problem: WhatsApp inbound auto-reply can deliver a captioned MEDIA: directive twice: first as an empty media-only message, then again as the final captioned media reply.
• Why it matters: Users receive duplicate WhatsApp images even though the assistant emitted one final response with one MEDIA: directive.
• What changed: Buffer media-only interim WhatsApp auto-reply payloads and drop the buffered payload when a later block/final payload carries the same media URL with visible caption text.
• What did NOT change (scope boundary): Low-level WhatsApp media sending, CLI message send --media, and legitimate tool-only/media-only replies are preserved.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Bug]: WhatsApp auto-reply sends MEDIA directive attachment twice for captioned replies #78767
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: WhatsApp inbound auto-reply delivered media-only interim payloads immediately, then later delivered the final captioned payload with the same media URL.
• Missing detection / guardrail: The dispatcher did not coalesce same-media interim/final deliveries before handing them to WhatsApp delivery.
• Contributing context (if known): The assistant trajectory can contain one final visible response with MEDIA:..., while the dispatcher lifecycle can still surface an earlier media-only payload for the same media.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: extensions/whatsapp/src/auto-reply/monitor/inbound-dispatch.test.ts
• Scenario the test should lock in: a media-only interim payload with /tmp/generated.jpg is not sent when a later block payload contains the same media URL plus caption text.
• Why this is the smallest reliable guardrail: The duplicate is created in the WhatsApp inbound dispatch lifecycle before low-level delivery, so the dispatcher unit test catches it without live WhatsApp credentials.
• Existing test that already covers this (if any): existing delivery tests cover low-level media send behavior, but not lifecycle duplicate coalescing.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

WhatsApp auto-replies for captioned MEDIA: directives now send one captioned media message instead of an empty media message followed by the same captioned media message.

Diagram (if applicable)

Before:
media-only interim -> WhatsApp send
final caption + same media -> WhatsApp send again

After:
media-only interim -> buffer
final caption + same media -> replace buffered payload -> WhatsApp sends once

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Ubuntu/Linux VPS
• Runtime/container: Node 22, local OpenClaw checkout
• Model/provider: existing configured agent
• Integration/channel (if any): WhatsApp default, linked and healthy
• Relevant config (redacted): loopback gateway, systemd user service

Steps

1. Ensure a small local image exists, e.g. media/whatsapp-tests/live-media-directive.png.
2. From WhatsApp, send:

   Reply with exactly these two lines, no markdown, no code fence, no extra text:
   WhatsApp inbound MEDIA directive live test
   MEDIA:media/whatsapp-tests/live-media-directive.png
   

3. Watch redacted logs for Sent media reply and auto-reply sent (media).

Expected

• One WhatsApp media reply with caption text.

Actual

• Before this fix, WhatsApp sent the same image twice: first media-only, then captioned media.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Redacted failing live log shape:

Sent media reply to +<redacted> (0.00MB)
auto-reply sent (media) {"text":"","mediaUrl":"<outbound-media>","mediaKind":"image"}
Sent media reply to +<redacted> (0.00MB)
auto-reply sent (media) {"text":"WhatsApp inbound MEDIA directive live test","mediaUrl":"<outbound-media>","mediaKind":"image"}

Validation:

pnpm exec oxfmt --check --threads=1 extensions/whatsapp/src/auto-reply/monitor/inbound-dispatch.ts extensions/whatsapp/src/auto-reply/monitor/inbound-dispatch.test.ts CHANGELOG.md
pnpm test extensions/whatsapp/src/auto-reply/monitor/inbound-dispatch.test.ts extensions/whatsapp/src/auto-reply/deliver-reply.test.ts -- --reporter=verbose
pnpm check:changed
git diff --check

Real behavior proof

• Behavior or issue addressed: WhatsApp inbound auto-reply for one captioned MEDIA: directive sent the same image twice, first as empty media and then as the captioned media reply.
• Real environment tested: Ubuntu 24.04 VPS, Node 22, local OpenClaw checkout, linked and healthy WhatsApp default channel, loopback Gateway, live WhatsApp direct chat.
• Exact steps or command run after this patch:
  1. Ran the local OpenClaw Gateway from this checkout.
  2. Sent this WhatsApp prompt to the linked OpenClaw number:

     Reply with exactly these two lines, no markdown, no code fence, no extra text:
     WhatsApp inbound MEDIA directive live test
     MEDIA:media/whatsapp-tests/live-media-directive.png
     

  3. Tailed redacted OpenClaw runtime logs for Inbound message, Sent media reply, and auto-reply sent (media).
• Evidence after fix: Redacted runtime log from the live WhatsApp run:

  2026-05-07T03:01:32.497Z info gateway/channels/whatsapp/inbound Inbound message +<redacted> -> +<redacted> (direct, 294 chars)
  2026-05-07T03:01:48.688Z info gateway/channels/whatsapp/outbound Sent media reply to +<redacted> (0.00MB)
  2026-05-07T03:01:48.690Z info web-auto-reply {"text":"WhatsApp inbound MEDIA directive live test","mediaUrl":"<outbound-media>","mediaSizeBytes":91,"mediaKind":"image"} auto-reply sent (media)
  

• Observed result after fix: The live WhatsApp run produced one captioned media reply and no second auto-reply sent (media) line after waiting.
• What was not tested: No additional gaps beyond the redacted live WhatsApp setup above; automated regression tests cover the dispatcher replacement behavior and the tool-only media flush edge case.

Human Verification (required)

• Verified scenarios: targeted WhatsApp dispatcher regression, low-level WhatsApp delivery tests, and previous live VPS reproduction with redacted logs.
• Edge cases checked: tool-only media still flushes and sends when no final replacement arrives; provider rejection still avoids rememberSentText.
• What you did not verify: additional handset/browser screenshots beyond the redacted live WhatsApp log proof above.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: buffering media-only interim payloads could suppress legitimate media-only replies.
  • Mitigation: pending media-only payloads flush after the dispatcher completes when no same-media final replacement arrives, with unit coverage for tool-only media turns.