openclaw - 💡(How to fix) Fix Bug: WhatsApp message_received hook omits media metadata

Summary

WhatsApp inbound media is downloaded and included in the canonical inbound hook context, but the plugin message_received event drops the media fields before invoking plugin hooks. As a result, plugins that listen to message_received cannot process images, PDFs, spreadsheets, or other downloaded attachments because they do not receive mediaPath, mediaType, or the related multi-media fields.

This is separate from, but related to, #86390: even when message_received hooks are emitted, the hook payload is missing media metadata.

Environment

• OpenClaw: 2026.5.20
• WhatsApp plugin: @openclaw/[email protected]
• Channel: WhatsApp multi-account inbound listener
• Hook: plugin message_received

What I observed

For an inbound WhatsApp image message:

1. The WhatsApp gateway received the media message.
2. The runtime downloaded the image and populated the inbound context with fields equivalent to MediaPath and MediaType.
3. The plugin message_received hook was emitted.
4. The plugin event metadata did not include mediaPath, mediaType, mediaPaths, mediaTypes, mediaUrl, or mediaUrls.

This makes downstream media-aware plugins unable to process attachments from message_received, even though the runtime already has the media metadata.

Code path

In the installed package, deriveInboundMessageHookContext(ctx, overrides) derives media metadata from the inbound context, including:

• mediaPath
• mediaUrl
• mediaType
• mediaPaths
• mediaUrls
• mediaTypes

toPluginInboundClaimEvent(canonical, extras) includes those fields in metadata, but toPluginMessageReceivedEvent(canonical) omits them.

So the media metadata exists in the canonical context but is lost for the message_received plugin event.

Expected behavior

toPluginMessageReceivedEvent(canonical) should include the same media metadata fields in event.metadata that are already available on the canonical inbound context:

mediaPath: canonical.mediaPath,
mediaUrl: canonical.mediaUrl,
mediaType: canonical.mediaType,
mediaPaths: canonical.mediaPaths,
mediaUrls: canonical.mediaUrls,
mediaTypes: canonical.mediaTypes,

This would allow message_received plugins to process images/PDFs/files without scraping logs or using a separate hook path.

Actual behavior

The plugin receives normal text/message metadata, but media metadata is absent. Media-aware workflows cannot reliably detect or process attachments from message_received.

Impact

Any plugin that needs to archive, OCR, classify, scan, or otherwise process WhatsApp attachments from message_received cannot do so reliably. The only workarounds are local runtime patches or brittle log scraping.

Suggested fix

Add the media fields to toPluginMessageReceivedEvent(canonical).metadata. This is a narrow change because the fields are already derived and already exposed on a related inbound plugin event.

Additional note

A first-class WhatsApp listen-only/hooks-only mode is still needed separately, but this bug is specifically about preserving media metadata once message_received is emitted.