@lofa199419/waha-v2 2.1.0

package/src/config-schema.ts

@@ -0,0 +1,342 @@
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk";
+import { z } from "zod";
+
+const allowFromEntry = z.union([z.string(), z.number()]);
+
+/**
+ * Typing indicator and message-chunking config exposed to the control UI.
+ */
+const WahaV2TypingConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    chunking: z.boolean().optional(),
+    charsPerSecond: z.number().int().positive().optional(),
+    maxChunkLength: z.number().int().positive().optional(),
+    debug: z.boolean().optional(),
+  })
+  .optional();
+
+const WahaV2LabelRuleSchema = z.object({
+  match: z.string(),
+  instruction: z.string(),
+  by: z.enum(["name", "id"]).optional(),
+});
+
+const WahaV2LabelRoutingConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    defaultInstruction: z.string().optional(),
+    rules: z.array(WahaV2LabelRuleSchema).optional(),
+    cacheTtlSec: z.number().int().positive().optional(),
+    autoAssignPersonal: z.boolean().optional(),
+    personalLabel: z.string().optional(),
+    pauseLabels: z.array(z.string()).optional(),
+  })
+  .optional();
+
+/**
+ * Per-group action enable/disable flags exposed to the control UI.
+ * Each field defaults to `true` (enabled) when omitted.
+ */
+const WahaV2ActionConfigSchema = z
+  .object({
+    sessionManagement: z.boolean().optional(),
+    messaging: z.boolean().optional(),
+    chats: z.boolean().optional(),
+    contacts: z.boolean().optional(),
+    groups: z.boolean().optional(),
+    status: z.boolean().optional(),
+    waChannels: z.boolean().optional(),
+  })
+  .optional();
+
+/**
+ * Config schema for a single WAHA account (root or nested under accounts.*).
+ */
+const WahaV2AccountSchema = z.object({
+  /** Whether this account is enabled. */
+  enabled: z.boolean().optional(),
+
+  /** Friendly display name for this account. */
+  name: z.string().optional(),
+
+  /** Base URL of the WAHA HTTP API instance. */
+  baseUrl: z.string().optional(),
+
+  /** API key for authenticating with WAHA. */
+  apiKey: z.string().optional(),
+
+  /** WAHA session name to use (defaults to "default"). */
+  session: z.string().optional(),
+
+  /**
+   * Public URL WAHA will POST inbound messages to.
+   * Example: https://your-openclaw-host/webhooks/waha-v2
+   * The gateway appends /{accountId} automatically.
+   */
+  webhookUrl: z.string().optional(),
+
+  /** DM access policy. */
+  dmPolicy: z.enum(["allow", "deny"]).optional(),
+
+  /** Group access policy. */
+  groupPolicy: z.enum(["allow", "deny", "allowlist"]).optional(),
+
+  /** Debounce inbound bursts per chat before dispatching to the agent. */
+  debounceMs: z.number().int().min(0).optional(),
+
+  /** Allowlist of group JIDs allowed when groupPolicy=allowlist (e.g. 1203...@g.us). */
+  allowGroups: z.array(allowFromEntry).optional(),
+
+  /** Allowlist of WhatsApp JIDs allowed to message this account (e.g. 15550001234@c.us). */
+  allowFrom: z.array(allowFromEntry).optional(),
+
+  /** Pause the bot whenever the WhatsApp owner sends any message in the chat. */
+  pauseOnOwnerMessage: z.boolean().optional(),
+
+  /** Owner-authored message texts that pause the bot immediately, e.g. ["//"]. */
+  ownerPauseWords: z.array(z.string()).optional(),
+
+  /** Owner-authored message texts that resume a manually paused chat, e.g. ["///"]. */
+  ownerResumeWords: z.array(z.string()).optional(),
+
+  /**
+   * Action group enable/disable flags.
+   * Controls which categories of agent actions are available for this account.
+   */
+  actions: WahaV2ActionConfigSchema,
+
+  /** Typing indicator and message-chunking behaviour. */
+  typing: WahaV2TypingConfigSchema,
+
+  /** Label-based inbound instruction routing. */
+  labelRouting: WahaV2LabelRoutingConfigSchema,
+});
+
+/**
+ * Full channels.waha-v2 config schema.
+ * Top-level fields are the default account; additional accounts live under `accounts`.
+ */
+export const WahaV2ConfigSchema = WahaV2AccountSchema.extend({
+  /** Additional named accounts — each key is an accountId. */
+  accounts: z.record(z.string(), WahaV2AccountSchema).optional(),
+});
+
+export type WahaV2Config = z.infer<typeof WahaV2ConfigSchema>;
+
+/**
+ * Channel config schema exposed to the control UI.
+ * `buildChannelConfigSchema` converts the Zod schema to JSON Schema Draft-7.
+ * uiHints add labels, placeholders, and sensitivity flags for each field.
+ */
+export const wahaV2ChannelConfigSchema = {
+  ...buildChannelConfigSchema(WahaV2ConfigSchema),
+  uiHints: {
+    baseUrl: {
+      label: "WAHA Server URL",
+      help: "Base URL of your self-hosted WAHA instance.",
+      placeholder: "https://waha.example.com",
+    },
+    apiKey: {
+      label: "API Key",
+      sensitive: true,
+      help: "Authentication key for the WAHA HTTP API.",
+      placeholder: "your-api-key",
+    },
+    session: {
+      label: "Session Name",
+      help: 'WAHA session name to use. Defaults to "default".',
+      placeholder: "default",
+    },
+    webhookUrl: {
+      label: "Webhook URL",
+      help: "Public URL WAHA will POST inbound messages to. Must be reachable by your WAHA server. The gateway appends /{accountId} automatically.",
+      placeholder: "https://your-openclaw-host/webhooks/waha-v2",
+    },
+    dmPolicy: {
+      label: "DM Policy",
+      help: "Whether to allow or deny direct messages from unknown contacts.",
+      advanced: true,
+    },
+    groupPolicy: {
+      label: "Group Policy",
+      help: "Whether to allow, deny, or allowlist group messages for this account.",
+      advanced: true,
+    },
+    debounceMs: {
+      label: "Inbound Debounce (ms)",
+      help: "Wait this long for follow-up messages from the same chat before dispatching one reply cycle.",
+      advanced: true,
+      placeholder: "1200",
+    },
+    allowGroups: {
+      label: "Allow Groups",
+      help: "Allowlist of group JIDs when Group Policy is allowlist. Format: 1203...@g.us",
+      advanced: true,
+    },
+    allowFrom: {
+      label: "Allow From",
+      help: "Allowlist of WhatsApp JIDs allowed to message this account. Leave empty to allow all. Format: 15550001234@c.us",
+      advanced: true,
+    },
+    pauseOnOwnerMessage: {
+      label: "Pause On Owner Message",
+      help: "Pause the bot for a chat when the connected WhatsApp owner sends any message in that chat.",
+      advanced: true,
+    },
+    ownerPauseWords: {
+      label: "Owner Pause Words",
+      help: 'Owner-authored texts that pause the bot immediately. Example: ["//"].',
+      advanced: true,
+    },
+    ownerResumeWords: {
+      label: "Owner Resume Words",
+      help: 'Owner-authored texts that resume a manually paused chat. Example: ["///"].',
+      advanced: true,
+    },
+    name: {
+      label: "Account Label",
+      help: "Friendly name for this account (displayed in the UI).",
+      advanced: true,
+      placeholder: "My WhatsApp",
+    },
+    enabled: {
+      label: "Enabled",
+      help: "Enable or disable this WAHA account.",
+    },
+    accounts: {
+      label: "Additional Accounts",
+      help: "Configure multiple WAHA accounts (each with its own server, API key, and session). Keyed by account ID.",
+      advanced: true,
+    },
+    actions: {
+      label: "Action Groups",
+      help: "Enable or disable categories of agent actions. All groups are enabled by default.",
+      advanced: true,
+    },
+    "actions.sessionManagement": {
+      label: "Session Management",
+      help: "Allow agents to start sessions, scan QR codes, request pairing codes, and log out.",
+      advanced: true,
+    },
+    "actions.messaging": {
+      label: "Messaging Actions",
+      help: "Allow agents to react, mark seen, send locations/contacts, forward, star, edit, delete, and pin messages.",
+      advanced: true,
+    },
+    "actions.chats": {
+      label: "Chat Actions",
+      help: "Allow agents to list chats, read history, archive/unarchive, delete chats, and mark as unread.",
+      advanced: true,
+    },
+    "actions.contacts": {
+      label: "Contact Actions",
+      help: "Allow agents to look up, check, block, and unblock contacts.",
+      advanced: true,
+    },
+    "actions.groups": {
+      label: "Group Actions",
+      help: "Allow agents to create and manage groups, participants, admins, and invite codes.",
+      advanced: true,
+    },
+    "actions.status": {
+      label: "Status / Stories",
+      help: "Allow agents to post and delete WhatsApp Status (Stories).",
+      advanced: true,
+    },
+    "actions.waChannels": {
+      label: "WA Channels (Newsletters)",
+      help: "Allow agents to list, read, create, and delete WhatsApp Channels (newsletters).",
+      advanced: true,
+    },
+    typing: {
+      label: "Typing & Chunking",
+      help: "Control the typing indicator and how long replies are split into multiple messages.",
+      advanced: true,
+    },
+    "typing.enabled": {
+      label: "Typing Indicator",
+      help: "Show the 'typing…' indicator in WhatsApp while the agent is composing a reply.",
+      advanced: true,
+    },
+    "typing.chunking": {
+      label: "Message Chunking",
+      help: "Split long replies into multiple messages at paragraph breaks for a more natural feel.",
+      advanced: true,
+    },
+    "typing.charsPerSecond": {
+      label: "Typing Speed (chars/sec)",
+      help: "Simulated typing speed used to calculate the delay between chunks. Default: 12 (≈ 2-3 words/s).",
+      advanced: true,
+      placeholder: "12",
+    },
+    "typing.maxChunkLength": {
+      label: "Max Chunk Length",
+      help: "Maximum number of characters per message chunk before splitting further. Default: 1500.",
+      advanced: true,
+      placeholder: "1500",
+    },
+    "typing.debug": {
+      label: "Typing Debug Logs",
+      help: "Emit detailed seen, typing, and chunk-delivery timing logs for WAHA replies.",
+      advanced: true,
+    },
+    labelRouting: {
+      label: "Label Routing",
+      help: "Inject instruction guardrails based on WhatsApp chat labels.",
+      advanced: true,
+    },
+    "labelRouting.enabled": {
+      label: "Enable Label Routing",
+      help: "When enabled, inbound messages are enriched with instructions based on chat labels.",
+      advanced: true,
+    },
+    "labelRouting.defaultInstruction": {
+      label: "Default Instruction",
+      help: "Fallback instruction used when no label rule matches.",
+      advanced: true,
+    },
+    "labelRouting.rules": {
+      label: "Label Rules",
+      help: "Ordered rules. First matching label injects its instruction.",
+      advanced: true,
+    },
+    "labelRouting.rules[].match": {
+      label: "Match Label",
+      help: "Label name or ID to match.",
+      advanced: true,
+    },
+    "labelRouting.rules[].by": {
+      label: "Match By",
+      help: "Match by label name (default) or label ID.",
+      advanced: true,
+    },
+    "labelRouting.rules[].instruction": {
+      label: "Instruction",
+      help: "Instruction text injected into agent context when the rule matches.",
+      advanced: true,
+    },
+    "labelRouting.cacheTtlSec": {
+      label: "Label Cache TTL (sec)",
+      help: "How long to cache chat-label lookups. Default: 120 seconds.",
+      advanced: true,
+      placeholder: "120",
+    },
+    "labelRouting.autoAssignPersonal": {
+      label: "Auto Assign Personal",
+      help: "Automatically add the personal label when an inbound message looks non-business.",
+      advanced: true,
+    },
+    "labelRouting.personalLabel": {
+      label: "Personal Label",
+      help: "Label name or ID to assign for non-business chats. Default: personal",
+      advanced: true,
+      placeholder: "personal",
+    },
+    "labelRouting.pauseLabels": {
+      label: "Pause Labels",
+      help: 'Labels that make the bot stay silent for a chat. Example: ["owner_intervention"].',
+      advanced: true,
+    },
+  },
+};

package/src/deliver.ts

@@ -0,0 +1,70 @@
+/**
+ * WhatsApp-specific reply delivery helpers.
+ *
+ * Chunks a long agent reply into multiple WhatsApp messages (splitting at
+ * paragraph breaks), and calculates a proportional human-like typing delay
+ * for each chunk so the conversation feels natural.
+ */
+import { chunkTextForOutbound } from "openclaw/plugin-sdk";
+
+/** Maximum characters per WhatsApp message chunk (well under the 4096 limit). */
+const MAX_CHUNK_LENGTH = 1500;
+
+/**
+ * Assumed human typing speed in characters per second.
+ * ~12 chars/s ≈ 2-3 words/s — noticeably human without feeling sluggish.
+ */
+const CHARS_PER_SECOND = 12;
+
+/** Minimum typing delay shown before a chunk, in ms. */
+const MIN_DELAY_MS = 600;
+
+/** Maximum typing delay cap — keeps the bot from stalling on very long chunks. */
+const MAX_DELAY_MS = 8000;
+
+/**
+ * Split a reply into multiple WhatsApp messages.
+ *
+ * Strategy:
+ *  1. Split at paragraph breaks (`\n\n`).
+ *  2. If a paragraph still exceeds `maxLength`, break it further at
+ *     newline/space boundaries via `chunkTextForOutbound`.
+ *  3. Always returns at least one non-empty chunk.
+ */
+export function chunkWahaMessage(text: string, maxLength = MAX_CHUNK_LENGTH): string[] {
+  const paragraphs = text.split(/\n\n+/);
+  const chunks: string[] = [];
+
+  for (const para of paragraphs) {
+    const trimmed = para.trim();
+    if (!trimmed) continue;
+
+    if (trimmed.length <= maxLength) {
+      chunks.push(trimmed);
+    } else {
+      // Paragraph too long — split at word/line boundaries.
+      for (const sub of chunkTextForOutbound(trimmed, maxLength)) {
+        const s = sub.trim();
+        if (s) chunks.push(s);
+      }
+    }
+  }
+
+  // Fallback: if the entire text had no paragraph breaks and didn't split, return as-is.
+  return chunks.length > 0 ? chunks : [text.trim()].filter(Boolean);
+}
+
+/**
+ * Calculate a human-like typing delay proportional to the chunk length.
+ *
+ * `delay = clamp(length / charsPerSecond * 1000, MIN_DELAY_MS, MAX_DELAY_MS)`
+ *
+ * Examples at the default speed of 12 chars/s:
+ *  - 50-char chunk  → 4 167 ms → clamped to 4 167 ms
+ *  - 15-char chunk  → 1 250 ms
+ *  - 300-char chunk → 25 000 ms → clamped to MAX (8 000 ms)
+ */
+export function calcTypingDelayMs(text: string, charsPerSecond = CHARS_PER_SECOND): number {
+  const raw = Math.round((text.length / charsPerSecond) * 1000);
+  return Math.max(MIN_DELAY_MS, Math.min(MAX_DELAY_MS, raw));
+}

package/src/gateway.ts

@@ -0,0 +1,170 @@
+import type { ChannelGatewayAdapter } from "openclaw/plugin-sdk";
+import { createWahaV2Client } from "./client.js";
+import { probeWahaV2Session } from "./probe.js";
+import { getWahaV2Logger } from "./runtime.js";
+import { removeWahaV2Client, setWahaV2Client } from "./runtime.js";
+import type { ResolvedWahaV2Account } from "./types.js";
+
+const HEALTH_INTERVAL_MS = 60_000;
+
+// Statuses that mean the session exists but is not running — we can start it.
+const STARTABLE_STATUSES = new Set(["STOPPED", "FAILED"]);
+
+// WAHA webhook events we care about.
+const WEBHOOK_EVENTS = ["message", "message.any", "session.status"];
+
+/** Build the webhook config block to embed in session create/update calls. */
+function buildWebhookConfig(webhookBaseUrl: string, accountId: string): Record<string, unknown> {
+  const url = `${webhookBaseUrl.replace(/\/+$/, "")}/${accountId}`;
+  return {
+    webhooks: [
+      {
+        url,
+        events: WEBHOOK_EVENTS,
+        retries: { policy: "exponential", delaySeconds: 2, attempts: 15 },
+      },
+    ],
+    // Keep WhatsApp Status/Stories out of the agent pipeline.
+    ignore: {
+      status: true,
+    },
+  };
+}
+
+/** Resolves when the abort signal fires or the delay elapses, whichever is first. */
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}
+
+export const wahaV2Gateway: ChannelGatewayAdapter<ResolvedWahaV2Account> = {
+  startAccount: async ({ cfg: _cfg, account, abortSignal, setStatus, log }) => {
+    const client = createWahaV2Client({
+      baseUrl: account.baseUrl,
+      apiKey: account.apiKey || undefined,
+    });
+
+    setWahaV2Client(account.accountId, client);
+
+    // Build webhook config once — reused in create and update calls.
+    const webhookConfig = account.webhookUrl
+      ? buildWebhookConfig(account.webhookUrl, account.accountId)
+      : undefined;
+
+    // Initial probe — check the live session status.
+    let probe = await probeWahaV2Session(client, account.session).catch(() => ({
+      ok: false,
+      status: undefined as string | undefined,
+    }));
+
+    if (!probe.ok && !abortSignal.aborted) {
+      const sessionStatus = String(probe.status ?? "").toUpperCase();
+
+      if (STARTABLE_STATUSES.has(sessionStatus)) {
+        // Session exists but is stopped — start it, then update webhook config separately.
+        log?.info(`waha-v2: session "${account.session}" is STOPPED — starting`);
+        await client.startSession(account.session).catch((err) => {
+          getWahaV2Logger().warn(
+            `waha-v2: startSession failed for "${account.session}": ${String(err)}`,
+          );
+        });
+        // Wait for WAHA to bring it up before attempting the webhook update.
+        if (!abortSignal.aborted) await sleep(5_000, abortSignal);
+        if (webhookConfig && !abortSignal.aborted) {
+          await client.updateSession(account.session, webhookConfig).catch((err) => {
+            getWahaV2Logger().warn(
+              `waha-v2: webhook update failed for "${account.session}": ${String(err)}`,
+            );
+          });
+        }
+      } else if (!sessionStatus) {
+        // Session doesn't exist — create it with webhook config baked in (one API call, no race).
+        log?.info(`waha-v2: session "${account.session}" not found — creating`);
+        await client.createSession(account.session, webhookConfig).catch((err) => {
+          getWahaV2Logger().warn(
+            `waha-v2: createSession failed for "${account.session}": ${String(err)}`,
+          );
+        });
+        if (webhookConfig) {
+          log?.info(`waha-v2: webhook embedded in session create for "${account.session}"`);
+        }
+      }
+
+      // Re-probe after startup attempt.
+      if (!abortSignal.aborted) {
+        await sleep(3_000, abortSignal);
+        if (!abortSignal.aborted) {
+          probe = await probeWahaV2Session(client, account.session).catch(() => ({
+            ok: false,
+            status: undefined,
+          }));
+        }
+      }
+    } else if (probe.ok && webhookConfig && !abortSignal.aborted) {
+      // Session already running — update webhook config to ensure it's current.
+      await client.updateSession(account.session, webhookConfig).catch((err) => {
+        getWahaV2Logger().warn(
+          `waha-v2: webhook update failed for "${account.session}": ${String(err)}`,
+        );
+      });
+      log?.info(`waha-v2: updated webhook URL for already-running session "${account.session}"`);
+    }
+
+    setStatus({
+      accountId: account.accountId,
+      running: true,
+      connected: probe.ok,
+      lastStartAt: Date.now(),
+      ...(probe.ok ? {} : { lastError: `session "${account.session}" not WORKING yet` }),
+    });
+
+    log?.info(
+      `waha-v2: account "${account.accountId}" started — ` +
+        `baseUrl=${account.baseUrl} session=${account.session} connected=${probe.ok}`,
+    );
+
+    // Health monitoring — re-probe every 60 s and update connected state.
+    let healthInterval: ReturnType<typeof setInterval> | null = setInterval(async () => {
+      if (abortSignal.aborted) return;
+      const health = await probeWahaV2Session(client, account.session).catch(() => ({ ok: false }));
+      setStatus({ accountId: account.accountId, running: true, connected: health.ok });
+    }, HEALTH_INTERVAL_MS);
+
+    abortSignal.addEventListener(
+      "abort",
+      () => {
+        if (healthInterval) {
+          clearInterval(healthInterval);
+          healthInterval = null;
+        }
+      },
+      { once: true },
+    );
+
+    await new Promise<void>((resolve) => {
+      abortSignal.addEventListener("abort", () => resolve(), { once: true });
+    });
+
+    removeWahaV2Client(account.accountId);
+    log?.info(`waha-v2: account "${account.accountId}" stopped`);
+  },
+
+  stopAccount: async ({ account, setStatus }) => {
+    removeWahaV2Client(account.accountId);
+    setStatus({
+      accountId: account.accountId,
+      running: false,
+      connected: false,
+      lastStopAt: Date.now(),
+    });
+  },
+};

package/src/login.ts

@@ -0,0 +1,64 @@
+import type { WahaV2Client } from "./client.js";
+
+// ---------------------------------------------------------------------------
+// Per-account login lock — prevents concurrent pairing attempts
+// ---------------------------------------------------------------------------
+
+const LOCK_TTL_MS = 30_000;
+
+const loginLocks = new Map<string, number>(); // accountId → expiry timestamp
+
+export class WahaV2LoginBusyError extends Error {
+  readonly statusCode = 409;
+  constructor(accountId: string) {
+    super(`waha-v2: login already in progress for account "${accountId}"`);
+    this.name = "WahaV2LoginBusyError";
+  }
+}
+
+export function acquireLoginLock(accountId: string): void {
+  const expiry = loginLocks.get(accountId);
+  if (expiry !== undefined && expiry > Date.now()) {
+    throw new WahaV2LoginBusyError(accountId);
+  }
+  loginLocks.set(accountId, Date.now() + LOCK_TTL_MS);
+}
+
+export function releaseLoginLock(accountId: string): void {
+  loginLocks.delete(accountId);
+}
+
+// ---------------------------------------------------------------------------
+// Wait for session to become connected (polls every 2 s until timeout)
+// ---------------------------------------------------------------------------
+
+const POLL_INTERVAL_MS = 2_000;
+const WAHA_CONNECTED_STATUSES = new Set(["WORKING", "CONNECTED", "AUTHENTICATED"]);
+
+export async function waitForWahaV2Connected(
+  client: WahaV2Client,
+  session: string,
+  timeoutMs: number,
+): Promise<{ ok: boolean; status?: string }> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const sessions = await client.listSessions(true).catch(() => []);
+    const target = session.trim().toLowerCase();
+    const found = sessions.find(
+      (s) =>
+        String(s.name ?? "")
+          .trim()
+          .toLowerCase() === target,
+    );
+    const status = String(found?.status ?? "")
+      .trim()
+      .toUpperCase();
+    if (WAHA_CONNECTED_STATUSES.has(status)) {
+      return { ok: true, status: found?.status };
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    await new Promise<void>((r) => setTimeout(r, Math.min(POLL_INTERVAL_MS, remaining)));
+  }
+  return { ok: false };
+}