BlueBubbles: enrich group participants with Contacts names

tyler6204 · tyler6204 · commit 2f7fc7de3e63 · 2026-03-26T00:01:56.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -36,6 +36,7 @@ Docs: https://docs.openclaw.ai
 - CLI/message send: write manual `openclaw message send` deliveries into the resolved agent session transcript again by always threading the default CLI agent through outbound mirroring. (#54187) Thanks @KevInTheCloud5617.
 - CLI/onboarding: show the Kimi Code API key option again in the Moonshot setup menu so the interactive picker includes all Kimi setup paths together. Fixes #54412 Thanks @sparkyrider
 - WhatsApp: fix infinite echo loop in self-chat DM mode where the bot's own outbound replies were re-processed as new inbound user messages. (#54570) Thanks @joelnishanth
+- BlueBubbles/groups: enrich participant lists with local macOS Contacts names when available, so group member context shows names instead of only raw phone numbers.
 
 ## 2026.3.24
 
diff --git a/extensions/bluebubbles/src/monitor-processing.ts b/extensions/bluebubbles/src/monitor-processing.ts
@@ -33,6 +33,7 @@ import type {
   BlueBubblesRuntimeEnv,
   WebhookTarget,
 } from "./monitor-shared.js";
+import { enrichBlueBubblesParticipantsWithContactNames } from "./participant-contact-names.js";
 import { isBlueBubblesPrivateApiEnabled } from "./probe.js";
 import { normalizeBlueBubblesReactionInput, sendBlueBubblesReaction } from "./reactions.js";
 import type { OpenClawConfig } from "./runtime-api.js";
@@ -460,6 +461,12 @@ export async function processMessage(
 
   const groupFlag = resolveGroupFlagFromChatGuid(message.chatGuid);
   const isGroup = typeof groupFlag === "boolean" ? groupFlag : message.isGroup;
+  if (isGroup && message.participants?.length) {
+    // BlueBubbles only gives us participant handles, so enrich phone numbers from local Contacts.
+    message.participants = await enrichBlueBubblesParticipantsWithContactNames(
+      message.participants,
+    );
+  }
 
   const text = message.text.trim();
   const attachments = message.attachments ?? [];
diff --git a/extensions/bluebubbles/src/monitor.test.ts b/extensions/bluebubbles/src/monitor.test.ts
@@ -23,6 +23,10 @@ import {
   setupWebhookTargetsForTest,
   trackWebhookRegistrationForTest,
 } from "./monitor.webhook.test-helpers.js";
+import {
+  resetBlueBubblesParticipantContactNameCacheForTest,
+  setBlueBubblesParticipantContactDepsForTest,
+} from "./participant-contact-names.js";
 import type { OpenClawConfig, PluginRuntime } from "./runtime-api.js";
 
 // Mock dependencies
@@ -185,12 +189,17 @@ describe("BlueBubbles webhook monitor", () => {
       hasControlCommandMock: mockHasControlCommand,
       resolveCommandAuthorizedFromAuthorizersMock: mockResolveCommandAuthorizedFromAuthorizers,
       buildMentionRegexesMock: mockBuildMentionRegexes,
-      extraReset: resetBlueBubblesSelfChatCache,
+      extraReset: () => {
+        resetBlueBubblesSelfChatCache();
+        resetBlueBubblesParticipantContactNameCacheForTest();
+        setBlueBubblesParticipantContactDepsForTest();
+      },
     });
   });
 
   afterEach(() => {
     unregister?.();
+    setBlueBubblesParticipantContactDepsForTest();
     vi.useRealTimers();
   });
 
@@ -489,6 +498,37 @@ describe("BlueBubbles webhook monitor", () => {
       expect(callArgs.ctx.GroupSubject).toBe("Family");
       expect(callArgs.ctx.GroupMembers).toBe("Alice (+15551234567), Bob (+15557654321)");
     });
+
+    it("enriches unnamed phone participants from local contacts before building ctx", async () => {
+      setupWebhookTarget();
+      setBlueBubblesParticipantContactDepsForTest({
+        platform: "darwin",
+        resolvePhoneNames: vi.fn(
+          async (phoneKeys: string[]) =>
+            new Map(
+              phoneKeys.map((phoneKey) => [
+                phoneKey,
+                phoneKey === "5551234567" ? "Alice Contact" : "Bob Contact",
+              ]),
+            ),
+        ),
+      });
+
+      const payload = createTimestampedNewMessagePayloadForTest({
+        text: "hello group",
+        isGroup: true,
+        chatGuid: "iMessage;+;chat123456",
+        chatName: "Family",
+        participants: [{ address: "+15551234567" }, { address: "+15557654321" }],
+      });
+
+      await dispatchWebhookPayload(payload);
+
+      const callArgs = getFirstDispatchCall();
+      expect(callArgs.ctx.GroupMembers).toBe(
+        "Alice Contact (+15551234567), Bob Contact (+15557654321)",
+      );
+    });
   });
 
   describe("group sender identity in envelope", () => {
diff --git a/extensions/bluebubbles/src/participant-contact-names.test.ts b/extensions/bluebubbles/src/participant-contact-names.test.ts
@@ -0,0 +1,92 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  enrichBlueBubblesParticipantsWithContactNames,
+  resetBlueBubblesParticipantContactNameCacheForTest,
+} from "./participant-contact-names.js";
+
+describe("enrichBlueBubblesParticipantsWithContactNames", () => {
+  beforeEach(() => {
+    resetBlueBubblesParticipantContactNameCacheForTest();
+  });
+
+  it("enriches unnamed phone participants and reuses cached names across formats", async () => {
+    const resolver = vi.fn(
+      async (phoneKeys: string[]) =>
+        new Map(
+          phoneKeys.map((phoneKey) => [
+            phoneKey,
+            phoneKey === "5551234567" ? "Alice Example" : "Bob Example",
+          ]),
+        ),
+    );
+
+    const first = await enrichBlueBubblesParticipantsWithContactNames(
+      [{ id: "+1 (555) 123-4567" }, { id: "+15557654321" }],
+      {
+        platform: "darwin",
+        now: () => 1_000,
+        resolvePhoneNames: resolver,
+      },
+    );
+
+    expect(first).toEqual([
+      { id: "+1 (555) 123-4567", name: "Alice Example" },
+      { id: "+15557654321", name: "Bob Example" },
+    ]);
+    expect(resolver).toHaveBeenCalledTimes(1);
+    expect(resolver).toHaveBeenCalledWith(["5551234567", "5557654321"]);
+
+    const secondResolver = vi.fn(async () => new Map<string, string>());
+    const second = await enrichBlueBubblesParticipantsWithContactNames([{ id: "+15551234567" }], {
+      platform: "darwin",
+      now: () => 2_000,
+      resolvePhoneNames: secondResolver,
+    });
+
+    expect(second).toEqual([{ id: "+15551234567", name: "Alice Example" }]);
+    expect(secondResolver).not.toHaveBeenCalled();
+  });
+
+  it("skips email addresses and keeps existing participant names", async () => {
+    const resolver = vi.fn(async () => new Map<string, string>());
+
+    const participants = await enrichBlueBubblesParticipantsWithContactNames(
+      [{ id: "alice@example.com" }, { id: "+15551234567", name: "Alice Existing" }],
+      {
+        platform: "darwin",
+        now: () => 1_000,
+        resolvePhoneNames: resolver,
+      },
+    );
+
+    expect(participants).toEqual([
+      { id: "alice@example.com" },
+      { id: "+15551234567", name: "Alice Existing" },
+    ]);
+    expect(resolver).not.toHaveBeenCalled();
+  });
+
+  it("gracefully returns original participants when lookup fails", async () => {
+    const participants = [{ id: "+15551234567" }, { id: "+15557654321" }];
+
+    await expect(
+      enrichBlueBubblesParticipantsWithContactNames(participants, {
+        platform: "darwin",
+        now: () => 1_000,
+        resolvePhoneNames: vi.fn(async () => {
+          throw new Error("contacts unavailable");
+        }),
+      }),
+    ).resolves.toBe(participants);
+  });
+
+  it("skips contact lookup on non macOS hosts", async () => {
+    const participants = [{ id: "+15551234567" }];
+
+    const result = await enrichBlueBubblesParticipantsWithContactNames(participants, {
+      platform: "linux",
+    });
+
+    expect(result).toBe(participants);
+  });
+});
diff --git a/extensions/bluebubbles/src/participant-contact-names.ts b/extensions/bluebubbles/src/participant-contact-names.ts
