fix(imessage): preserve media echo key

omarshahine · omarshahine · commit 5ad977655381 · 2026-05-13T08:43:39.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- iMessage: stop sending visible `<media:image>` placeholder text for media-only native image sends while preserving the internal echo key that prevents self-echo duplicate replies. (#81209) Thanks @homer-byte.
 - gateway: pass Talk session scope to resolver [AI]. (#81379) Thanks @pgondhi987.
 - Gateway protocol: require v4 clients and stream explicit chat `deltaText`/`replace` frames so SDK clients can consume assistant updates without local diffing. (#80725) Thanks @samzong.
 - OpenAI plugin: clarify remote Codex OAuth login copy so tunneled users know sign-in may finish automatically before they paste the redirect URL. (#81301) Thanks @rubencu.
diff --git a/extensions/imessage/src/monitor/deliver.test.ts b/extensions/imessage/src/monitor/deliver.test.ts
@@ -237,11 +237,12 @@ describe("deliverReplies", () => {
     });
   });
 
-  it("records the actual sent placeholder for media-only replies", async () => {
+  it("records the internal echo key for media-only replies", async () => {
     const remember = vi.fn();
     sendMessageIMessageMock.mockResolvedValueOnce({
       messageId: "imsg-media-1",
-      sentText: "<media:image>",
+      sentText: "",
+      echoText: "<media:image>",
     });
 
     await deliverReplies({
diff --git a/extensions/imessage/src/monitor/deliver.ts b/extensions/imessage/src/monitor/deliver.ts
@@ -58,7 +58,10 @@ export async function deliverReplies(params: {
         // not before. The window between send completion and cache write is sub-millisecond;
         // the next SQLite inbound poll is 1-2s away, so no echo can arrive before the
         // cache entry exists.
-        sentMessageCache?.remember(scope, { text: sent.sentText, messageId: sent.messageId });
+        sentMessageCache?.remember(scope, {
+          text: sent.echoText ?? sent.sentText,
+          messageId: sent.messageId,
+        });
       },
       sendMedia: async ({ mediaUrl, caption }) => {
         const sent = await sendMessageIMessage(target, caption ?? "", {
@@ -70,7 +73,7 @@ export async function deliverReplies(params: {
           replyToId: payload.replyToId,
         });
         sentMessageCache?.remember(scope, {
-          text: sent.sentText || undefined,
+          text: sent.echoText ?? (sent.sentText || undefined),
           messageId: sent.messageId,
         });
       },
@@ -94,7 +97,7 @@ export function createIMessageEchoCachingSend(params: {
     });
     const scope = `${params.accountId ?? opts.accountId ?? ""}:${target}`;
     params.sentMessageCache?.remember(scope, {
-      text: sent.sentText || undefined,
+      text: sent.echoText ?? (sent.sentText || undefined),
       messageId: sent.messageId,
     });
     return sent;
diff --git a/extensions/imessage/src/send.test.ts b/extensions/imessage/src/send.test.ts
@@ -31,6 +31,7 @@ describe("sendMessageIMessage receipts", () => {
 
     expect(result.messageId).toBe("p:0/imsg-1");
     expect(result.sentText).toBe("hello");
+    expect(result.echoText).toBe("hello");
     expect(result.receipt.primaryPlatformMessageId).toBe("p:0/imsg-1");
     expect(result.receipt.platformMessageIds).toEqual(["p:0/imsg-1"]);
     expect(result.receipt.replyToId).toBe("reply-1");
@@ -71,6 +72,7 @@ describe("sendMessageIMessage receipts", () => {
 
     expect(result.messageId).toBe("12345");
     expect(result.sentText).toBe("");
+    expect(result.echoText).toBe("<media:image>");
     expect(result.receipt.primaryPlatformMessageId).toBe("12345");
     expect(result.receipt.platformMessageIds).toEqual(["12345"]);
     expect(client.request).toHaveBeenCalledWith(
@@ -115,6 +117,7 @@ describe("sendMessageIMessage receipts", () => {
     });
 
     expect(result.sentText).toBe("literal <media:image> text");
+    expect(result.echoText).toBe("literal <media:image> text");
     expect(client.request).toHaveBeenCalledWith(
       "send",
       expect.objectContaining({
diff --git a/extensions/imessage/src/send.ts b/extensions/imessage/src/send.ts
@@ -6,7 +6,7 @@ import {
 } from "openclaw/plugin-sdk/channel-message";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import { resolveMarkdownTableMode } from "openclaw/plugin-sdk/markdown-table-runtime";
-import { resolveOutboundAttachmentFromUrl } from "openclaw/plugin-sdk/media-runtime";
+import { kindFromMime, resolveOutboundAttachmentFromUrl } from "openclaw/plugin-sdk/media-runtime";
 import { requireRuntimeConfig } from "openclaw/plugin-sdk/plugin-config-runtime";
 import { convertMarkdownTables } from "openclaw/plugin-sdk/text-chunking";
 import { stripInlineDirectiveTagsForDelivery } from "openclaw/plugin-sdk/text-chunking";
@@ -47,6 +47,7 @@ type IMessageSendOpts = {
 type IMessageSendResult = {
   messageId: string;
   sentText: string;
+  echoText?: string;
   receipt: MessageReceipt;
 };
 
@@ -93,6 +94,17 @@ function resolveMessageId(result: Record<string, unknown> | null | undefined): s
   return raw ? raw.trim() : null;
 }
 
+function resolveOutboundEchoText(text: string, mediaContentType?: string): string | undefined {
+  if (text.trim()) {
+    return text;
+  }
+  const kind = kindFromMime(mediaContentType ?? undefined);
+  if (!kind) {
+    return undefined;
+  }
+  return kind === "image" ? "<media:image>" : `<media:${kind}>`;
+}
+
 function createIMessageSendReceipt(params: {
   messageId: string;
   target: ReturnType<typeof parseIMessageTarget>;
@@ -175,6 +187,7 @@ export async function sendMessageIMessage(
         : 16 * 1024 * 1024;
   let message = text ?? "";
   let filePath: string | undefined;
+  let mediaContentType: string | undefined;
 
   if (opts.mediaUrl?.trim()) {
     const resolveAttachmentFn = opts.resolveAttachmentImpl ?? resolveOutboundAttachmentFromUrl;
@@ -183,6 +196,7 @@ export async function sendMessageIMessage(
       readFile: opts.mediaReadFile,
     });
     filePath = resolved.path;
+    mediaContentType = resolved.contentType ?? undefined;
   }
 
   if (!message.trim() && !filePath) {
@@ -211,6 +225,7 @@ export async function sendMessageIMessage(
   if (!message.trim() && !filePath) {
     throw new Error("iMessage send requires text or media");
   }
+  const echoText = resolveOutboundEchoText(message, filePath ? mediaContentType : undefined);
   const resolvedReplyToId = sanitizeReplyToId(opts.replyToId);
   const params: Record<string, unknown> = {
     text: message,
@@ -253,7 +268,7 @@ export async function sendMessageIMessage(
     if (echoScope) {
       rememberPersistedIMessageEcho({
         scope: echoScope,
-        text: message,
+        text: echoText,
         messageId: resolvedId ?? undefined,
       });
     }
@@ -280,6 +295,7 @@ export async function sendMessageIMessage(
     return {
       messageId,
       sentText: message,
+      ...(echoText ? { echoText } : {}),
       receipt: createIMessageSendReceipt({
         messageId,
         target,
