feat(whatsapp): add wacli tools and bump version

Author: ivangdavila

whatsapp/README.md

@@ -1,8 +1,8 @@
 # WhatsApp Plugin
 
-Skill-first OpenClaw plugin for sending third-party WhatsApp messages and searching synced history through the local `wacli` CLI.
+OpenClaw plugin for working with WhatsApp through the local `wacli` CLI.
 
-It is meant for operational messaging, history search, and sync tasks. It is not for normal back-and-forth chats with the user.
+It exposes real tools for operational messaging, history search, diagnostics, and backfill. It is not for normal back-and-forth chats with the user.
 
 ## Requirements
 
@@ -19,6 +19,38 @@ Keep sync running when you want continuous indexing:
 wacli sync --follow
 ```
 
+## Config
+
+```json5
+{
+  plugins: {
+    entries: {
+      whatsapp: {
+        enabled: true,
+        config: {
+          wacliPath: "/opt/homebrew/bin/wacli",
+          storePath: "~/.wacli",
+          requireExplicitSendConfirmation: true,
+          defaultChatListLimit: 20,
+          defaultMessageSearchLimit: 20,
+        },
+      },
+    },
+  },
+}
+```
+
+`wacliPath` is optional if `wacli` is already on `PATH`.
+
+## Tools
+
+- `whatsapp_chats_list`
+- `whatsapp_messages_search`
+- `whatsapp_history_backfill`
+- `whatsapp_doctor`
+- `whatsapp_send_text`
+- `whatsapp_send_file`
+
 ## Usage
 
 After enabling `whatsapp`, ask for things like:
@@ -28,4 +60,4 @@ After enabling `whatsapp`, ask for things like:
 - Send a WhatsApp message to +14155551212 saying that the files are ready.
 - Send `/tmp/agenda.pdf` to the team group with caption "Agenda".
 
-The skill works best when the request includes an explicit recipient, exact message text, and a verified chat or phone number.
+The send tools require `confirm=true` by default so the agent cannot send a real message without an explicit confirmation step.

whatsapp/dist/index.js

@@ -1,7 +1,289 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { Type } from "@sinclair/typebox";
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+const execFileAsync = promisify(execFile);
+const DEFAULT_CHAT_LIST_LIMIT = 20;
+const DEFAULT_MESSAGE_SEARCH_LIMIT = 20;
+function toolTextResult(text, details) {
+    return {
+        content: [{ type: "text", text }],
+        details,
+    };
+}
+function pickString(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+function pickNumber(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "number" && Number.isFinite(value))
+            return value;
+        if (typeof value === "string" && value.trim()) {
+            const parsed = Number(value);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+    }
+    return undefined;
+}
+function ensureArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function normalizeConfig(input) {
+    const config = {};
+    if (typeof input.wacliPath === "string" && input.wacliPath.trim()) {
+        config.wacliPath = input.wacliPath.trim();
+    }
+    if (typeof input.storePath === "string" && input.storePath.trim()) {
+        config.storePath = input.storePath.trim();
+    }
+    if (typeof input.requireExplicitSendConfirmation === "boolean") {
+        config.requireExplicitSendConfirmation = input.requireExplicitSendConfirmation;
+    }
+    if (typeof input.defaultChatListLimit === "number") {
+        config.defaultChatListLimit = input.defaultChatListLimit;
+    }
+    if (typeof input.defaultMessageSearchLimit === "number") {
+        config.defaultMessageSearchLimit = input.defaultMessageSearchLimit;
+    }
+    return config;
+}
+function baseArgs(config, json) {
+    const args = [];
+    if (config.storePath) {
+        args.push("--store", config.storePath);
+    }
+    if (json) {
+        args.push("--json");
+    }
+    return args;
+}
+async function runWacli(config, args, options = {}) {
+    const command = config.wacliPath ?? "wacli";
+    const commandArgs = [...baseArgs(config, Boolean(options.json)), ...args];
+    const { stdout, stderr } = await execFileAsync(command, commandArgs, {
+        encoding: "utf8",
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    const text = stdout.trim();
+    const parsed = options.json && text ? JSON.parse(text) : undefined;
+    return {
+        command,
+        commandArgs,
+        stdout: text,
+        stderr: stderr.trim(),
+        parsed,
+    };
+}
+function formatChatList(chats) {
+    const entries = ensureArray(chats).filter((value) => !!value && typeof value === "object");
+    if (!entries.length)
+        return "No WhatsApp chats found.";
+    return [
+        "WhatsApp chats",
+        ...entries.map((chat, index) => {
+            const name = pickString(chat, ["Name", "name", "DisplayName", "displayName", "PushName", "pushName"]) ??
+                "Unnamed chat";
+            const jid = pickString(chat, ["JID", "jid", "ChatJID", "chatJid"]) ?? "unknown";
+            const unread = pickNumber(chat, ["UnreadCount", "unreadCount"]);
+            return `${index + 1}. ${name} (${jid})${typeof unread === "number" ? ` unread:${unread}` : ""}`;
+        }),
+    ].join("\n");
+}
+function formatMessageList(messages) {
+    const entries = ensureArray(messages).filter((value) => !!value && typeof value === "object");
+    if (!entries.length)
+        return "No WhatsApp messages matched the search.";
+    return [
+        "Matching WhatsApp messages",
+        ...entries.map((message, index) => {
+            const chat = pickString(message, ["ChatJID", "chatJid", "JID", "jid"]) ?? "unknown-chat";
+            const sender = pickString(message, ["Sender", "sender", "SenderName", "senderName", "Author", "author"]) ??
+                "unknown";
+            const body = pickString(message, ["Text", "text", "Body", "body", "Message", "message", "DisplayText"]) ??
+                "(no text)";
+            const timestamp = pickString(message, ["Timestamp", "timestamp", "CreatedAt", "createdAt", "Time", "time"]) ?? "";
+            return `${index + 1}. [${chat}] ${sender}${timestamp ? ` @ ${timestamp}` : ""}: ${body}`;
+        }),
+    ].join("\n");
+}
+function ensureSendConfirmed(config, confirm) {
+    if (config.requireExplicitSendConfirmation === false)
+        return;
+    if (confirm)
+        return;
+    throw new Error("This tool sends a real WhatsApp message. Retry with confirm=true after verifying the target.");
+}
 export default definePluginEntry({
     id: "whatsapp",
     name: "WhatsApp",
-    description: "Guide WhatsApp automation inside OpenClaw using the local wacli CLI",
-    register() { },
+    description: "Search chats, backfill history, run diagnostics, and send WhatsApp messages through wacli",
+    register(api) {
+        const config = normalizeConfig((api.pluginConfig ?? {}));
+        api.registerTool({
+            name: "whatsapp_chats_list",
+            label: "List WhatsApp chats",
+            description: "List WhatsApp chats from the local wacli store, optionally filtered by name or number",
+            parameters: Type.Object({
+                query: Type.Optional(Type.String({ minLength: 1 })),
+                limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 200 })),
+            }),
+            async execute(_id, params) {
+                const result = await runWacli(config, [
+                    "chats",
+                    "list",
+                    "--limit",
+                    String(params.limit ?? config.defaultChatListLimit ?? DEFAULT_CHAT_LIST_LIMIT),
+                    ...(params.query ? ["--query", params.query] : []),
+                ], { json: true });
+                const chats = ensureArray(result.parsed);
+                return toolTextResult(formatChatList(chats), {
+                    status: "ok",
+                    count: chats.length,
+                    chats,
+                    command: [result.command, ...result.commandArgs],
+                });
+            },
+        });
+        api.registerTool({
+            name: "whatsapp_messages_search",
+            label: "Search WhatsApp messages",
+            description: "Search synced WhatsApp messages by query, chat JID, or date range",
+            parameters: Type.Object({
+                query: Type.String({ minLength: 1 }),
+                chat: Type.Optional(Type.String({ minLength: 1 })),
+                after: Type.Optional(Type.String({ minLength: 1 })),
+                before: Type.Optional(Type.String({ minLength: 1 })),
+                limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 200 })),
+            }),
+            async execute(_id, params) {
+                const result = await runWacli(config, [
+                    "messages",
+                    "search",
+                    params.query,
+                    "--limit",
+                    String(params.limit ?? config.defaultMessageSearchLimit ?? DEFAULT_MESSAGE_SEARCH_LIMIT),
+                    ...(params.chat ? ["--chat", params.chat] : []),
+                    ...(params.after ? ["--after", params.after] : []),
+                    ...(params.before ? ["--before", params.before] : []),
+                ], { json: true });
+                const messages = ensureArray(result.parsed);
+                return toolTextResult(formatMessageList(messages), {
+                    status: "ok",
+                    count: messages.length,
+                    messages,
+                    command: [result.command, ...result.commandArgs],
+                });
+            },
+        });
+        api.registerTool({
+            name: "whatsapp_history_backfill",
+            label: "Backfill WhatsApp history",
+            description: "Request best-effort historical message sync for one chat from the linked phone",
+            parameters: Type.Object({
+                chat: Type.String({ minLength: 1 }),
+                requests: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
+                count: Type.Optional(Type.Integer({ minimum: 1, maximum: 500 })),
+            }),
+            async execute(_id, params) {
+                const result = await runWacli(config, [
+                    "history",
+                    "backfill",
+                    "--chat",
+                    params.chat,
+                    "--requests",
+                    String(params.requests ?? 2),
+                    "--count",
+                    String(params.count ?? 50),
+                ]);
+                return toolTextResult([`History backfill requested for ${params.chat}.`, result.stdout].filter(Boolean).join("\n"), {
+                    status: "ok",
+                    chat: params.chat,
+                    stdout: result.stdout,
+                    command: [result.command, ...result.commandArgs],
+                });
+            },
+        });
+        api.registerTool({
+            name: "whatsapp_doctor",
+            label: "Run WhatsApp diagnostics",
+            description: "Run wacli doctor to inspect local WhatsApp CLI setup and auth state",
+            parameters: Type.Object({}, { additionalProperties: false }),
+            async execute() {
+                const result = await runWacli(config, ["doctor"]);
+                return toolTextResult(result.stdout || "wacli doctor completed.", {
+                    status: "ok",
+                    stdout: result.stdout,
+                    command: [result.command, ...result.commandArgs],
+                });
+            },
+        });
+        api.registerTool({
+            name: "whatsapp_send_text",
+            label: "Send WhatsApp text",
+            description: "Send a WhatsApp text message to a verified phone number or chat JID",
+            parameters: Type.Object({
+                to: Type.String({ minLength: 1 }),
+                message: Type.String({ minLength: 1 }),
+                confirm: Type.Optional(Type.Boolean()),
+            }),
+            async execute(_id, params) {
+                ensureSendConfirmed(config, params.confirm);
+                const result = await runWacli(config, [
+                    "send",
+                    "text",
+                    "--to",
+                    params.to,
+                    "--message",
+                    params.message,
+                ]);
+                return toolTextResult(result.stdout || `WhatsApp text sent to ${params.to}.`, {
+                    status: "sent",
+                    to: params.to,
+                    mode: "text",
+                    stdout: result.stdout,
+                    command: [result.command, ...result.commandArgs],
+                });
+            },
+        });
+        api.registerTool({
+            name: "whatsapp_send_file",
+            label: "Send WhatsApp file",
+            description: "Send a file to a WhatsApp phone number or chat JID with an optional caption",
+            parameters: Type.Object({
+                to: Type.String({ minLength: 1 }),
+                file: Type.String({ minLength: 1 }),
+                caption: Type.Optional(Type.String()),
+                filename: Type.Optional(Type.String()),
+                confirm: Type.Optional(Type.Boolean()),
+            }),
+            async execute(_id, params) {
+                ensureSendConfirmed(config, params.confirm);
+                const result = await runWacli(config, [
+                    "send",
+                    "file",
+                    "--to",
+                    params.to,
+                    "--file",
+                    params.file,
+                    ...(params.caption ? ["--caption", params.caption] : []),
+                    ...(params.filename ? ["--filename", params.filename] : []),
+                ]);
+                return toolTextResult(result.stdout || `WhatsApp file sent to ${params.to}.`, {
+                    status: "sent",
+                    to: params.to,
+                    mode: "file",
+                    file: params.file,
+                    stdout: result.stdout,
+                    command: [result.command, ...result.commandArgs],
+                });
+            },
+        });
+    },
 });