diff --git a/docs/plugins/compatibility.md b/docs/plugins/compatibility.md
index 171251280ca..9e30e3579f1 100644
--- a/docs/plugins/compatibility.md
+++ b/docs/plugins/compatibility.md
@@ -128,6 +128,10 @@ Current compatibility records include:
 - legacy runtime aliases such as `api.runtime.taskFlow`,
   `api.runtime.subagent.getSession`, `api.runtime.stt`, and deprecated
   `api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)`
+- WhatsApp `WebInboundMessage` flat callback fields such as `body`, `chatId`,
+  `reply(...)`, and `mediaPath` while callback consumers migrate to the nested
+  `WebInboundCallbackMessage` `event`, `payload`, `quote`, `group`, and
+  `platform` contexts
 - legacy memory-plugin split registration while memory plugins move to
   `registerMemoryCapability`
 - legacy memory-specific embedding provider registration while embedding
@@ -160,6 +164,33 @@ New plugin code should prefer the replacement listed in the registry and in the
 specific migration guide. Existing plugins can keep using a compatibility path
 until the docs, diagnostics, and release notes announce a removal window.
 
+### WhatsApp Inbound Callback Flat Aliases
+
+WhatsApp runtime callbacks deliver `WebInboundMessage`: the canonical nested
+`event`, `payload`, `quote`, `group`, and `platform` contexts plus deprecated
+flat aliases for the shipped callback fields. New callback code should read the
+nested contexts. Code that constructs clean nested callback messages can use
+`WebInboundCallbackMessage`; compatibility listeners that still inject old flat
+test or plugin messages should use `LegacyFlatWebInboundMessage` or
+`WebInboundMessageInput`.
+
+The flat aliases remain available until **2026-08-30**. That removal window
+applies only to flat alias access; the nested callback shape is the canonical
+runtime contract. The TypeScript `@deprecated` annotations on each flat alias
+name its exact nested replacement. Common examples:
+
+- `id`, `timestamp`, and `isBatched` move under `event`.
+- `body`, `mediaPath`, `mediaType`, `mediaFileName`, `mediaUrl`, `location`, and
+  `untrustedStructuredContext` move under `payload`.
+- `to`, `chatId`, sender/self fields, `sendComposing`, `reply(...)`, and
+  `sendMedia(...)` move under `platform`.
+- `replyTo*` fields move under `quote`, and group subject/participant/mention
+  fields move under `group`.
+
+`payload.untrustedStructuredContext` is extracted from inbound provider payloads.
+Plugins should inspect the `label`, `source`, and `type` before treating its
+`payload` as authoritative.
+
 ## Release notes
 
 Release notes should include upcoming plugin deprecations with target dates and
diff --git a/src/plugins/compat/registry.test.ts b/src/plugins/compat/registry.test.ts
index 2cb6a5061c0..c56ef98bf38 100644
--- a/src/plugins/compat/registry.test.ts
+++ b/src/plugins/compat/registry.test.ts
@@ -214,6 +214,11 @@ const knownDeprecatedSurfaceMarkers = [
     file: "src/plugin-sdk/messaging-targets.ts",
     marker: "openclaw/plugin-sdk/channel-targets",
   },
+  {
+    code: "whatsapp-web-inbound-flat-message-aliases",
+    file: "extensions/whatsapp/src/inbound/types.ts",
+    marker: "DeprecatedWebInboundMessageFlatAliases",
+  },
 ] as const;
 
 function parseDate(date: string): Date {
diff --git a/src/plugins/compat/registry.ts b/src/plugins/compat/registry.ts
index dfd6fb0cc89..5f29af2265f 100644
--- a/src/plugins/compat/registry.ts
+++ b/src/plugins/compat/registry.ts
@@ -166,6 +166,27 @@ export const PLUGIN_COMPAT_RECORDS = [
       "src/plugins/captured-registration.test.ts",
     ],
   },
+  {
+    code: "whatsapp-web-inbound-flat-message-aliases",
+    status: "deprecated",
+    owner: "channel",
+    introduced: "2026-05-30",
+    deprecated: "2026-05-30",
+    warningStarts: "2026-05-30",
+    removeAfter: "2026-08-30",
+    replacement:
+      "WhatsApp `WebInboundCallbackMessage` nested contexts: `event`, `payload`, `quote`, `group`, and `platform`",
+    docsPath: "/plugins/compatibility",
+    surfaces: [
+      "@openclaw/whatsapp WebInboundMessage flat fields",
+      "WhatsApp monitorWebInbox onMessage callback",
+      "WhatsApp monitorWebChannel listenerFactory injected messages",
+    ],
+    diagnostics: ["TypeScript @deprecated WebInboundMessage flat field annotations"],
+    tests: ["src/plugins/compat/registry.test.ts"],
+    releaseNote:
+      "WhatsApp WebInboundMessage flat fields remain wired as deprecated aliases while callbacks migrate to nested inbound contexts.",
+  },
   {
     code: "bundled-channel-sdk-compat-facades",
     status: "active",