@emotion-machine/claw-messenger 0.1.12 → 0.1.14

package/README.md

@@ -57,8 +57,17 @@ The plugin registers two tools your agent can call:
 2. Create an API key from the dashboard
 3. Install the plugin: `openclaw plugins install @emotion-machine/claw-messenger`
 4. Add the config above with your API key
-5. Start a conversation — your agent can now send and receive messages
+5. Restart OpenClaw so the channel connects
+6. Check the listener before the first controlled send:
+
+   ```bash
+   curl https://claw-messenger.onrender.com/api/agent/readiness \
+     -H "Authorization: Bearer ${CLAW_API_KEY}"
+   ```
+
+   Continue only after the response is `{"ready":true,"action":"send_controlled_test"}`. If the action is `connect_agent`, restart OpenClaw and check again. Keep the key in the authorization header, never in the URL.
+7. Send one message to a phone you control, reply in the same thread, and confirm the reply reaches your agent
 
 ## License
 
-UNLICENSED
+UNLICENSED

package/dist/channel.d.ts

@@ -1,6 +1,7 @@
 import type { ChannelPlugin } from "openclaw/plugin-sdk";
 import { type ClawMessengerConfig } from "./config.js";
 import { WsClient } from "./ws/client.js";
+import { type SendResult } from "./outbound/send.js";
 interface ResolvedAccount {
     accountId: string;
     enabled: boolean;
@@ -18,8 +19,7 @@ export declare function getConnectionStatus(): {
 };
 export declare function createGroup(to: string[], text: string): Promise<{
     ok: boolean;
-    messageId: string;
-    chatId: string;
-}>;
+} & SendResult>;
 export declare const clawMessengerPlugin: ChannelPlugin<ResolvedAccount>;
+export declare function handleInboundMessage(data: Record<string, unknown>, accountId: string, account: ResolvedAccount, ctx: any): Promise<void>;
 export {};

package/dist/channel.js

@@ -1,5 +1,6 @@
 import * as pluginSdk from "openclaw/plugin-sdk";
 import { ClawMessengerConfigSchema } from "./config.js";
+import { isInboundMessageEvent, normalizeInboundMessage, validateInboundRoute, } from "./inbound.js";
 import { getRuntime } from "./runtime.js";
 import { WsClient } from "./ws/client.js";
 import { normalizeDirectTarget, sendText, sendMedia, sendToGroup, sendGroupMedia, sendToNewGroup, } from "./outbound/send.js";
@@ -194,6 +195,7 @@ export const clawMessengerPlugin = {
             "You can react to messages using iMessage tapbacks via the react action. Available: love (❤️), like (👍), dislike (👎), laugh (😂), emphasize (‼️), question (❓).",
             "Use reactions naturally — the way a real person would in iMessage.",
             "If you encounter connection issues, the server is WebSocket-only — do NOT test with HTTP. Full API docs and troubleshooting: https://clawmessenger.com/docs",
+            "If a user is stuck connecting, the fix is almost always: make sure the Claw Messenger plugin is enabled and the API key is set. Verified setup guides to hand them: OpenClaw setup https://www.clawmessenger.com/blog/openclaw-imessage-setup-guide, Hermes setup https://www.clawmessenger.com/blog/hermes-imessage-setup, troubleshooting https://www.clawmessenger.com/blog/openclaw-imessage-troubleshooting.",
         ],
     },
     // Legacy API (OpenClaw <2026.3.22): kept for backward compatibility
@@ -369,7 +371,7 @@ export const clawMessengerPlugin = {
                     ctx.log?.warn?.(`[${resolvedAccountId}] Disconnected from claw-messenger`);
                 },
                 onMessage: async (data) => {
-                    if (data.type === "message") {
+                    if (isInboundMessageEvent(data)) {
                         // Track last message timestamp for sync on reconnect
                         lastMessageAt.set(resolvedAccountId, new Date().toISOString());
                         await handleInboundMessage(data, resolvedAccountId, account, ctx);
@@ -437,25 +439,38 @@ export const clawMessengerPlugin = {
 // versions doesn't include it. Newer OpenClaw calls this; older versions ignore it.
 clawMessengerPlugin.describeMessageTool = describeClawMessageTool;
 // -- Inbound message handler --
-async function handleInboundMessage(data, accountId, account, ctx) {
-    const from = data.from;
-    const text = data.text ?? "";
-    const messageId = data.messageId ?? "";
-    const attachments = data.attachments ?? [];
-    const isGroup = data.isGroup === true;
-    const chatId = data.chatId;
-    const participants = data.participants ?? [];
+export async function handleInboundMessage(data, accountId, account, ctx) {
+    const normalized = normalizeInboundMessage(data);
+    if (!normalized.ok) {
+        ctx.log?.warn?.(`[${accountId}] Dropping inbound message: ${normalized.reason}`);
+        return;
+    }
+    const { from, text, messageId, attachments, isGroup, chatId, participants, } = normalized.message;
     const runtime = getRuntime();
     const cfg = runtime.config.loadConfig();
     // Resolve routing — group by chatId, DM by sender phone
-    const route = runtime.channel.routing.resolveAgentRoute({
-        cfg,
-        channel: "claw-messenger",
-        accountId,
-        peer: isGroup
-            ? { kind: "group", id: chatId }
-            : { kind: "dm", id: from },
-    });
+    let rawRoute;
+    try {
+        rawRoute = runtime.channel.routing.resolveAgentRoute({
+            cfg,
+            channel: "claw-messenger",
+            accountId,
+            peer: isGroup
+                ? { kind: "group", id: chatId }
+                : { kind: "dm", id: from },
+        });
+    }
+    catch (err) {
+        ctx.log?.warn?.(`[${accountId}] Dropping inbound message from ${from}: route resolution failed (${err})`);
+        return;
+    }
+    const routeValidation = validateInboundRoute(rawRoute);
+    if (!routeValidation.ok) {
+        ctx.log?.warn?.(`[${accountId}] Dropping inbound message from ${from}: ${routeValidation.reason}`);
+        return;
+    }
+    const route = routeValidation.route;
+    const routeSessionKey = route.sessionKey;
     // Download media
     const allMedia = [];
     for (const attachment of attachments) {
@@ -473,7 +488,10 @@ async function handleInboundMessage(data, accountId, account, ctx) {
         agentId: route.agentId,
     });
     const envelopeOptions = runtime.channel.reply.resolveEnvelopeFormatOptions(cfg);
-    const previousTimestamp = runtime.channel.session.readSessionUpdatedAt(storePath, route.sessionKey);
+    const previousTimestamp = runtime.channel.session.readSessionUpdatedAt({
+        storePath,
+        sessionKey: routeSessionKey,
+    });
     const rawBody = text || (allMedia.length > 0 ? "<media:image>" : "");
     if (!rawBody)
         return;
@@ -493,8 +511,8 @@ async function handleInboundMessage(data, accountId, account, ctx) {
         CommandBody: rawBody,
         From: `claw-messenger:${from}`,
         To: `claw-messenger:shared`,
-        SessionKey: route.sessionKey,
-        AccountId: route.accountId,
+        SessionKey: routeSessionKey,
+        AccountId: route.accountId || accountId,
         ChatType: isGroup ? "group" : "direct",
         ConversationLabel: isGroup ? chatId : from,
         SenderId: from,
@@ -515,7 +533,7 @@ async function handleInboundMessage(data, accountId, account, ctx) {
     });
     void runtime.channel.session.recordSessionMetaFromInbound({
         storePath,
-        sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+        sessionKey: ctxPayload.SessionKey ?? routeSessionKey,
         ctx: ctxPayload,
     }).catch(() => { });
     const ws = wsClients.get(accountId);

package/dist/inbound.d.ts

@@ -0,0 +1,37 @@
+export interface InboundAttachment {
+    url: string;
+    mimeType?: string;
+}
+export interface NormalizedInboundMessage {
+    from: string;
+    text: string;
+    messageId: string;
+    attachments: InboundAttachment[];
+    isGroup: boolean;
+    chatId: string;
+    participants: string[];
+}
+export interface ResolvedInboundRoute {
+    sessionKey: string;
+    accountId: string;
+    agentId?: string;
+    mainSessionKey?: string;
+    [key: string]: unknown;
+}
+export type InboundMessageValidation = {
+    ok: true;
+    message: NormalizedInboundMessage;
+} | {
+    ok: false;
+    reason: string;
+};
+export type InboundRouteValidation = {
+    ok: true;
+    route: ResolvedInboundRoute;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function isInboundMessageEvent(data: Record<string, unknown>): boolean;
+export declare function normalizeInboundMessage(data: Record<string, unknown>): InboundMessageValidation;
+export declare function validateInboundRoute(route: unknown): InboundRouteValidation;

package/dist/inbound.js

@@ -0,0 +1,67 @@
+function nonBlankString(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}
+function normalizeAttachments(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((attachment) => {
+        if (!attachment || typeof attachment !== "object")
+            return [];
+        const url = nonBlankString(attachment.url);
+        if (!url)
+            return [];
+        const mimeType = nonBlankString(attachment.mimeType) ?? undefined;
+        return [{ url, mimeType }];
+    });
+}
+function normalizeStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map(nonBlankString).filter((item) => Boolean(item));
+}
+export function isInboundMessageEvent(data) {
+    return data.type === "message";
+}
+export function normalizeInboundMessage(data) {
+    const isGroup = data.isGroup === true;
+    const from = nonBlankString(data.from);
+    if (!from) {
+        return { ok: false, reason: "missing sender" };
+    }
+    const chatId = nonBlankString(data.chatId) ?? "";
+    if (isGroup && !chatId) {
+        return { ok: false, reason: "missing group chatId" };
+    }
+    return {
+        ok: true,
+        message: {
+            from,
+            text: nonBlankString(data.text) ?? "",
+            messageId: nonBlankString(data.messageId) ?? "",
+            attachments: normalizeAttachments(data.attachments),
+            isGroup,
+            chatId,
+            participants: normalizeStringArray(data.participants),
+        },
+    };
+}
+export function validateInboundRoute(route) {
+    if (!route || typeof route !== "object") {
+        return { ok: false, reason: "missing route" };
+    }
+    const sessionKey = nonBlankString(route.sessionKey);
+    if (!sessionKey) {
+        return { ok: false, reason: "missing route sessionKey" };
+    }
+    return {
+        ok: true,
+        route: {
+            ...route,
+            sessionKey,
+            accountId: nonBlankString(route.accountId) ?? "",
+        },
+    };
+}

package/dist/index.js

@@ -99,7 +99,7 @@ const plugin = {
                 const ws = getWsClient(status.accountId);
                 const diagnostics = ws?.getDiagnostics() ?? { errors: [], connectionLog: [] };
                 const report = {
-                    plugin_version: "0.1.11",
+                    plugin_version: "0.1.14",
                     node_version: process.version,
                     connected: status.connected,
                     server_url: status.serverUrl,

package/dist/outbound/send.d.ts

@@ -2,6 +2,19 @@ import type { WsClient } from "../ws/client.js";
 export interface SendResult {
     messageId: string;
     chatId: string;
+    status?: string;
+    requestedService?: string;
+    selectedService?: string;
+    fallbackAllowed?: boolean;
+    fallbackReason?: string;
+    deliveryStage?: string;
+    errorCode?: string;
+    retryable?: boolean;
+    setupProof?: {
+        required?: boolean;
+        status?: string;
+        message?: string;
+    };
 }
 export declare function normalizeDirectTarget(target: string): string | null;
 export declare function sendText(ws: WsClient, to: string, text: string, service?: string): Promise<SendResult>;

package/dist/outbound/send.js

@@ -60,10 +60,7 @@ export async function sendMessage(ws, to, parts, service) {
         ...(service ? { service } : {}),
     });
     if (resp.ok) {
-        return {
-            messageId: resp.messageId ?? "",
-            chatId: resp.chatId ?? "",
-        };
+        return sendResultFromResponse(resp);
     }
     throw new Error(resp.error ?? "Send failed");
 }
@@ -86,10 +83,7 @@ async function sendGroupMessage(ws, chatId, parts, service) {
         ...(service ? { service } : {}),
     });
     if (resp.ok) {
-        return {
-            messageId: resp.messageId ?? "",
-            chatId,
-        };
+        return sendResultFromResponse(resp, chatId);
     }
     throw new Error(resp.error ?? "Group send failed");
 }
@@ -107,10 +101,22 @@ export async function sendToNewGroup(ws, to, text, service) {
         ...(service ? { service } : {}),
     });
     if (resp.ok) {
-        return {
-            messageId: resp.messageId ?? "",
-            chatId: resp.chatId ?? "",
-        };
+        return sendResultFromResponse(resp);
     }
     throw new Error(resp.error ?? "Group creation failed");
 }
+function sendResultFromResponse(resp, fallbackChatId = "") {
+    return {
+        messageId: resp.messageId ?? "",
+        chatId: resp.chatId ?? fallbackChatId,
+        status: resp.status,
+        requestedService: resp.requestedService,
+        selectedService: resp.selectedService,
+        fallbackAllowed: resp.fallbackAllowed,
+        fallbackReason: resp.fallbackReason,
+        deliveryStage: resp.deliveryStage,
+        errorCode: resp.errorCode,
+        retryable: resp.retryable,
+        setupProof: resp.setupProof,
+    };
+}

package/dist/ws/client.js

@@ -7,6 +7,18 @@
  * against HTTP/2 servers like Render.com).
  */
 import WebSocket from "ws";
+import { createRequire } from "node:module";
+// Client fingerprint sent on the WS handshake so the server can tell which
+// integration (and version) is connecting. Version is read at runtime from
+// package.json; falls back to "unknown" in bundled environments without it.
+const CLIENT_ID = `openclaw-plugin/${(() => {
+    try {
+        return createRequire(import.meta.url)("../../package.json").version;
+    }
+    catch {
+        return "unknown";
+    }
+})()}`;
 const MAX_RECONNECT_DELAY_MS = 30_000;
 const MAX_RECONNECT_ATTEMPTS = 50;
 const MAX_DIAGNOSTIC_ENTRIES = 50;
@@ -119,6 +131,7 @@ export class WsClient {
             url.pathname = url.pathname.replace(/\/$/, "") + "/ws";
         }
         url.searchParams.set("key", this.opts.apiKey);
+        url.searchParams.set("client", CLIENT_ID);
         this.opts.log?.(`Connecting to ${url.origin}${url.pathname}...`);
         // Close the previous socket if it's still open, so we don't leak
         // connections on the server. Set this.ws to null first so the old

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@emotion-machine/claw-messenger",
-  "version": "0.1.12",
-  "description": "iMessage, RCS & SMS channel plugin for OpenClaw — no phone or Mac Mini required",
+  "version": "0.1.14",
+  "description": "iMessage, RCS & SMS channel plugin for OpenClaw agents, powered by Claw Messenger, the Mac-free iMessage API for AI agents. Send and receive real texts from Linux, Docker, Windows, or any cloud. No phone or Mac required.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,6 +18,10 @@
     "openclaw",
     "openclaw-plugin",
     "imessage",
+    "imessage-api",
+    "ai-agents",
+    "no-mac",
+    "claw-messenger",
     "rcs",
     "sms",
     "emotion-machine",
@@ -33,6 +37,7 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
+    "test": "npm run build && node --loader ./tests/openclaw-loader.mjs --test tests/*.test.mjs",
     "prepare": "test -d dist || npm run build",
     "prepublishOnly": "npm run clean && npm run build"
   },

package/src/types/openclaw.d.ts

@@ -199,7 +199,7 @@ declare module "openclaw/plugin-sdk" {
       };
       session: {
         resolveStorePath(store: any, opts?: { agentId?: string }): string;
-        readSessionUpdatedAt(path: string, sessionKey: string): number | null;
+        readSessionUpdatedAt(ctx: { storePath: string; sessionKey: string }): number | null;
         recordSessionMetaFromInbound(ctx: any): Promise<void>;
         recordInboundSession(ctx: any): void;
         updateLastRoute(ctx: any): void;