@lofa199419/waha-v2 2.1.0

package/src/outbound.ts

@@ -0,0 +1,84 @@
+import type { ChannelOutboundAdapter, PollInput } from "openclaw/plugin-sdk";
+import { loadWebMedia } from "openclaw/plugin-sdk";
+import { resolveWahaV2Account } from "./accounts.js";
+import { requireWahaV2Client } from "./runtime.js";
+import { WAHA_V2_CHANNEL_ID } from "./types.js";
+
+// WhatsApp has a 4096 character limit per message.
+const TEXT_CHUNK_LIMIT = 4096;
+
+function resolveMessageId(id: string | undefined, serialized: string | undefined): string {
+  return id ?? serialized ?? "";
+}
+
+export const wahaV2Outbound: ChannelOutboundAdapter = {
+  deliveryMode: "gateway",
+  chunkerMode: "text",
+  textChunkLimit: TEXT_CHUNK_LIMIT,
+  pollMaxOptions: 12,
+
+  async sendText({ cfg, to, text, accountId }) {
+    const account = resolveWahaV2Account(cfg, accountId);
+    const client = requireWahaV2Client(account.accountId);
+    const result = await client.sendText(account.session, to, text);
+    return {
+      channel: WAHA_V2_CHANNEL_ID,
+      messageId: resolveMessageId(result.id, result._serialized),
+    };
+  },
+
+  async sendMedia({ cfg, to, text, mediaUrl, accountId }) {
+    if (!mediaUrl) {
+      throw new Error("waha-v2: mediaUrl is required for media sends");
+    }
+    const account = resolveWahaV2Account(cfg, accountId);
+    const client = requireWahaV2Client(account.accountId);
+
+    // Fetch media from the URL provided by the agent framework.
+    const media = await loadWebMedia(mediaUrl);
+    const contentType =
+      (media.contentType ?? "application/octet-stream").split(";")[0]?.trim() ??
+      "application/octet-stream";
+    const filename = media.fileName ?? "file";
+    const file = {
+      data: media.buffer.toString("base64"),
+      mimetype: contentType,
+      filename,
+    };
+    const caption = text?.trim() || undefined;
+
+    let result;
+    if (contentType.startsWith("image/")) {
+      result = await client.sendImage(account.session, to, file, caption);
+    } else if (contentType.startsWith("video/")) {
+      result = await client.sendVideo(account.session, to, file, caption);
+    } else if (
+      contentType.startsWith("audio/") ||
+      filename.endsWith(".ogg") ||
+      filename.endsWith(".opus")
+    ) {
+      // Audio/voice notes use the WAHA sendVoice endpoint.
+      result = await client.sendVoice(account.session, to, file);
+    } else {
+      result = await client.sendFile(account.session, to, file, caption);
+    }
+
+    return {
+      channel: WAHA_V2_CHANNEL_ID,
+      messageId: resolveMessageId(result.id, result._serialized),
+    };
+  },
+
+  async sendPoll({ cfg, to, poll, accountId }) {
+    const account = resolveWahaV2Account(cfg, accountId);
+    const client = requireWahaV2Client(account.accountId);
+    const p = poll as PollInput;
+    const result = await client.sendPoll(account.session, to, {
+      name: p.question,
+      options: p.options,
+      // WAHA treats maxSelections > 1 as multi-answer; OpenClaw uses maxSelections.
+      multipleAnswers: (p.maxSelections ?? 1) > 1,
+    });
+    return { messageId: resolveMessageId(result.id, result._serialized) };
+  },
+};

package/src/probe.ts

@@ -0,0 +1,30 @@
+import type { WahaV2Client } from "./client.js";
+import type { WahaV2ProbeResult } from "./types.js";
+
+const WAHA_CONNECTED_STATUSES = new Set(["WORKING", "CONNECTED", "AUTHENTICATED"]);
+
+/**
+ * Probe a WAHA session's live connectivity status.
+ * Uses the sessions list endpoint and checks for the target session name.
+ */
+export async function probeWahaV2Session(
+  client: WahaV2Client,
+  session: string,
+): Promise<WahaV2ProbeResult> {
+  try {
+    const sessions = await client.listSessions(true);
+    const target = session.trim().toLowerCase();
+    const found = sessions.find(
+      (s) =>
+        String(s.name ?? "")
+          .trim()
+          .toLowerCase() === target,
+    );
+    const status = String(found?.status ?? "")
+      .trim()
+      .toUpperCase();
+    return { ok: WAHA_CONNECTED_STATUSES.has(status), status: found?.status };
+  } catch (err) {
+    return { ok: false, error: String(err) };
+  }
+}

package/src/routes.ts

@@ -0,0 +1,260 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { readJsonBodyWithLimit } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { resolveWahaV2Account } from "./accounts.js";
+import { acquireLoginLock, releaseLoginLock, waitForWahaV2Connected } from "./login.js";
+import { probeWahaV2Session } from "./probe.js";
+import { getWahaV2Client, getWahaV2Logger } from "./runtime.js";
+import { WAHA_V2_DEFAULT_ACCOUNT_ID, type WahaV2ProbeResult } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Route path constants — imported by index.ts when registering routes
+// ---------------------------------------------------------------------------
+
+export const WAHA_V2_API_BASE = "/plugins/waha-v2/api" as const;
+export const WAHA_V2_ROUTE_STATUS = `${WAHA_V2_API_BASE}/status` as const;
+export const WAHA_V2_ROUTE_START = `${WAHA_V2_API_BASE}/start` as const;
+export const WAHA_V2_ROUTE_QR = `${WAHA_V2_API_BASE}/qr` as const;
+export const WAHA_V2_ROUTE_REQUEST_CODE = `${WAHA_V2_API_BASE}/request-code` as const;
+export const WAHA_V2_ROUTE_WAIT = `${WAHA_V2_API_BASE}/wait` as const;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function parseUrl(req: IncomingMessage): URL {
+  return new URL(req.url ?? "/", "http://localhost");
+}
+
+function jsonOk(res: ServerResponse, data: unknown): void {
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify(data));
+}
+
+function jsonError(res: ServerResponse, code: number, message: string): void {
+  res.statusCode = code;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ ok: false, error: message }));
+}
+
+function resolveAccountIdFromRequest(url: URL, body?: Record<string, unknown>): string {
+  return String(url.searchParams.get("accountId") ?? body?.accountId ?? WAHA_V2_DEFAULT_ACCOUNT_ID);
+}
+
+// ---------------------------------------------------------------------------
+// GET /plugins/waha-v2/api/status
+// Returns the live session status for an account.
+// ---------------------------------------------------------------------------
+
+export async function handleWahaV2StatusRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  cfg: OpenClawConfig,
+): Promise<void> {
+  const url = parseUrl(req);
+  const accountId = resolveAccountIdFromRequest(url);
+  const account = resolveWahaV2Account(cfg, accountId);
+  const client = getWahaV2Client(account.accountId);
+  if (!client) {
+    return jsonError(res, 503, `gateway not running for account "${accountId}"`);
+  }
+  const probe = await probeWahaV2Session(client, account.session).catch(
+    (err): WahaV2ProbeResult => ({
+      ok: false,
+      error: String(err),
+    }),
+  );
+  jsonOk(res, {
+    ok: true,
+    accountId,
+    session: account.session,
+    connected: probe.ok,
+    status: probe.status ?? null,
+    error: probe.error ?? null,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// POST /plugins/waha-v2/api/start
+// Creates (if needed) and starts the WAHA session for an account.
+// ---------------------------------------------------------------------------
+
+export async function handleWahaV2StartRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  cfg: OpenClawConfig,
+): Promise<void> {
+  if (req.method !== "POST") {
+    return jsonError(res, 405, "Method Not Allowed");
+  }
+
+  const body = await readJsonBodyWithLimit(req, {
+    maxBytes: 64 * 1024,
+    timeoutMs: 5_000,
+    emptyObjectOnEmpty: true,
+  });
+  if (!body.ok) {
+    return jsonError(res, 400, body.error ?? "Bad Request");
+  }
+
+  const url = parseUrl(req);
+  const payload = body.value as Record<string, unknown>;
+  const accountId = resolveAccountIdFromRequest(url, payload);
+  const account = resolveWahaV2Account(cfg, accountId);
+  const client = getWahaV2Client(account.accountId);
+  if (!client) {
+    return jsonError(res, 503, `gateway not running for account "${accountId}"`);
+  }
+
+  try {
+    acquireLoginLock(accountId);
+  } catch (err) {
+    return jsonError(res, 409, String(err));
+  }
+
+  try {
+    // Try starting the existing session; if that fails, create it first (auto-starts).
+    await client.startSession(account.session).catch(async () => {
+      await client.createSession(account.session);
+    });
+    const probe = await probeWahaV2Session(client, account.session).catch(() => ({ ok: false }));
+    jsonOk(res, {
+      ok: true,
+      accountId,
+      session: account.session,
+      started: true,
+      connected: probe.ok,
+    });
+  } catch (err) {
+    getWahaV2Logger().warn(`waha-v2 start error for "${accountId}": ${String(err)}`);
+    jsonError(res, 500, String(err));
+  } finally {
+    releaseLoginLock(accountId);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// GET /plugins/waha-v2/api/qr
+// Returns the QR code (base64) for scanning in WhatsApp.
+// ---------------------------------------------------------------------------
+
+export async function handleWahaV2QrRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  cfg: OpenClawConfig,
+): Promise<void> {
+  const url = parseUrl(req);
+  const accountId = resolveAccountIdFromRequest(url);
+  const account = resolveWahaV2Account(cfg, accountId);
+  const client = getWahaV2Client(account.accountId);
+  if (!client) {
+    return jsonError(res, 503, `gateway not running for account "${accountId}"`);
+  }
+
+  try {
+    const qr = await client.getQr(account.session);
+    if (!qr?.data) {
+      return jsonError(
+        res,
+        404,
+        "QR not available — session may already be connected, not started, or not in QR pairing mode",
+      );
+    }
+    jsonOk(res, { ok: true, accountId, session: account.session, data: qr.data });
+  } catch (err) {
+    getWahaV2Logger().warn(`waha-v2 qr error for "${accountId}": ${String(err)}`);
+    jsonError(res, 500, String(err));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// POST /plugins/waha-v2/api/request-code
+// Requests a pairing code (auth code) for the given phone number.
+// Body: { accountId?: string, phoneNumber: string }
+// ---------------------------------------------------------------------------
+
+export async function handleWahaV2RequestCodeRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  cfg: OpenClawConfig,
+): Promise<void> {
+  if (req.method !== "POST") {
+    return jsonError(res, 405, "Method Not Allowed");
+  }
+
+  const body = await readJsonBodyWithLimit(req, {
+    maxBytes: 64 * 1024,
+    timeoutMs: 5_000,
+    emptyObjectOnEmpty: true,
+  });
+  if (!body.ok) {
+    return jsonError(res, 400, body.error ?? "Bad Request");
+  }
+
+  const url = parseUrl(req);
+  const payload = body.value as Record<string, unknown>;
+  const accountId = resolveAccountIdFromRequest(url, payload);
+  const phoneNumber = String(payload.phoneNumber ?? "").trim();
+  if (!phoneNumber) {
+    return jsonError(res, 400, "phoneNumber is required");
+  }
+
+  const account = resolveWahaV2Account(cfg, accountId);
+  const client = getWahaV2Client(account.accountId);
+  if (!client) {
+    return jsonError(res, 503, `gateway not running for account "${accountId}"`);
+  }
+
+  try {
+    acquireLoginLock(accountId);
+  } catch (err) {
+    return jsonError(res, 409, String(err));
+  }
+
+  try {
+    const result = await client.requestCode(account.session, phoneNumber);
+    jsonOk(res, {
+      ok: true,
+      accountId,
+      session: account.session,
+      code: result?.code ?? null,
+    });
+  } catch (err) {
+    getWahaV2Logger().warn(`waha-v2 request-code error for "${accountId}": ${String(err)}`);
+    jsonError(res, 500, String(err));
+  } finally {
+    releaseLoginLock(accountId);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// GET /plugins/waha-v2/api/wait
+// Long-polls until the session is connected (or timeout). Max 120 s.
+// Query params: accountId?, timeout? (ms, default 60000, max 120000)
+// ---------------------------------------------------------------------------
+
+export async function handleWahaV2WaitRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  cfg: OpenClawConfig,
+): Promise<void> {
+  const url = parseUrl(req);
+  const accountId = resolveAccountIdFromRequest(url);
+  const timeoutMs = Math.min(Number(url.searchParams.get("timeout") ?? 60_000), 120_000);
+
+  const account = resolveWahaV2Account(cfg, accountId);
+  const client = getWahaV2Client(account.accountId);
+  if (!client) {
+    return jsonError(res, 503, `gateway not running for account "${accountId}"`);
+  }
+
+  const result = await waitForWahaV2Connected(client, account.session, timeoutMs);
+  jsonOk(res, {
+    ok: result.ok,
+    accountId,
+    session: account.session,
+    connected: result.ok,
+    status: result.status ?? null,
+  });
+}

package/src/runtime.ts

@@ -0,0 +1,56 @@
+import type { PluginRuntime, RuntimeLogger } from "openclaw/plugin-sdk";
+import type { WahaV2Client } from "./client.js";
+
+// ---------------------------------------------------------------------------
+// Plugin-level runtime + logger (set once at plugin registration)
+// ---------------------------------------------------------------------------
+
+let pluginRuntime: PluginRuntime | null = null;
+let pluginLogger: RuntimeLogger | null = null;
+
+export function setWahaV2Runtime(runtime: PluginRuntime, logger: RuntimeLogger): void {
+  pluginRuntime = runtime;
+  pluginLogger = logger;
+}
+
+export function getWahaV2Runtime(): PluginRuntime {
+  if (!pluginRuntime) {
+    throw new Error("waha-v2: runtime not initialized");
+  }
+  return pluginRuntime;
+}
+
+export function getWahaV2Logger(): RuntimeLogger {
+  if (!pluginLogger) {
+    throw new Error("waha-v2: logger not initialized");
+  }
+  return pluginLogger;
+}
+
+// ---------------------------------------------------------------------------
+// Per-account client map (populated by gateway.startAccount)
+// ---------------------------------------------------------------------------
+
+const accountClients = new Map<string, WahaV2Client>();
+
+export function setWahaV2Client(accountId: string, client: WahaV2Client): void {
+  accountClients.set(accountId, client);
+}
+
+export function removeWahaV2Client(accountId: string): void {
+  accountClients.delete(accountId);
+}
+
+export function getWahaV2Client(accountId: string): WahaV2Client | undefined {
+  return accountClients.get(accountId);
+}
+
+export function requireWahaV2Client(accountId: string): WahaV2Client {
+  const client = accountClients.get(accountId);
+  if (!client) {
+    throw new Error(
+      `waha-v2: no active client for account "${accountId}" — gateway may not be running`,
+    );
+  }
+  return client;
+}

package/src/types.ts

@@ -0,0 +1,195 @@
+// ---------------------------------------------------------------------------
+// Config types — mirrors cfg.channels["waha-v2"] in OpenClaw config file
+// ---------------------------------------------------------------------------
+
+/**
+ * Typing indicator and message-chunking config for the WAHA v2 channel.
+ * All fields are optional; defaults produce natural human-like behaviour.
+ */
+export type WahaV2TypingConfig = {
+  /** Show "typing…" indicator while the agent composes a reply. Default: true */
+  enabled?: boolean;
+  /** Split long replies into multiple messages at paragraph breaks. Default: true */
+  chunking?: boolean;
+  /**
+   * Simulated typing speed in characters per second, used to compute
+   * the per-chunk delay: delay = clamp(length / charsPerSecond * 1000, min, max).
+   * Default: 12 (≈ 2-3 words/s).
+   */
+  charsPerSecond?: number;
+  /** Maximum characters per message chunk before splitting further. Default: 1500 */
+  maxChunkLength?: number;
+  /** Emit detailed delivery/typing timing logs for troubleshooting. Default: false */
+  debug?: boolean;
+};
+
+export type WahaV2LabelRule = {
+  /** Label name or ID to match (case-insensitive for name). */
+  match: string;
+  /** Instruction injected into BodyForAgent when the rule matches. */
+  instruction: string;
+  /** Match by label `name` (default) or `id`. */
+  by?: "name" | "id";
+};
+
+export type WahaV2LabelRoutingConfig = {
+  /** Enables label-based instruction injection for inbound messages. */
+  enabled?: boolean;
+  /** Fallback instruction when no label rule matches. */
+  defaultInstruction?: string;
+  /** Ordered list of matching rules; first match wins. */
+  rules?: WahaV2LabelRule[];
+  /** Cache TTL (seconds) for chat label lookups. Default: 120. */
+  cacheTtlSec?: number;
+  /** Auto-assign personal label when message appears non-business. */
+  autoAssignPersonal?: boolean;
+  /** Target label name or id used for non-business auto-assignment. Default: "personal". */
+  personalLabel?: string;
+  /** Labels that pause bot replies while present on the chat. */
+  pauseLabels?: string[];
+};
+
+/**
+ * Per-group action enable/disable flags for the WAHA v2 channel.
+ * Each key controls a category of agent actions; defaults to `true` (enabled).
+ */
+export type WahaV2ActionConfig = {
+  /** start/stop/QR/logout session management actions. */
+  sessionManagement?: boolean;
+  /** Message-level actions: react, seen, location, contact, forward, star, edit, delete, pin. */
+  messaging?: boolean;
+  /** Chat list/history/archive/delete actions. */
+  chats?: boolean;
+  /** Contact lookup/block/unblock actions. */
+  contacts?: boolean;
+  /** Group create/manage/participant/admin actions. */
+  groups?: boolean;
+  /** WhatsApp Status (Stories) send/delete actions. */
+  status?: boolean;
+  /** WhatsApp Channels (Newsletters) actions. */
+  waChannels?: boolean;
+};
+
+export type WahaV2AccountConfig = {
+  enabled?: boolean;
+  name?: string;
+  baseUrl?: string;
+  apiKey?: string;
+  session?: string;
+  /**
+   * Full public URL that WAHA should POST inbound events to.
+   * Example: "https://your-openclaw-host/webhooks/waha-v2"
+   * If set, the gateway registers it with the WAHA session on startup.
+   */
+  webhookUrl?: string;
+  dmPolicy?: string;
+  groupPolicy?: string;
+  debounceMs?: number;
+  allowFrom?: string[];
+  allowGroups?: string[];
+  /** Pause the bot for a chat when the WhatsApp owner sends any message in it. */
+  pauseOnOwnerMessage?: boolean;
+  /** Owner-authored message texts that pause the bot immediately, e.g. ["//"]. */
+  ownerPauseWords?: string[];
+  /** Owner-authored message texts that resume a manually paused chat, e.g. ["///"]. */
+  ownerResumeWords?: string[];
+  actions?: WahaV2ActionConfig;
+  typing?: WahaV2TypingConfig;
+  labelRouting?: WahaV2LabelRoutingConfig;
+};
+
+export type WahaV2RootConfig = WahaV2AccountConfig & {
+  accounts?: Record<string, WahaV2AccountConfig>;
+};
+
+export const WAHA_V2_CHANNEL_ID = "waha-v2" as const;
+export const WAHA_V2_DEFAULT_ACCOUNT_ID = "default" as const;
+/**
+ * Base path for inbound WAHA webhooks.
+ * Per-account paths are: `${WAHA_V2_WEBHOOK_BASE}/${accountId}`
+ * e.g. /webhooks/waha-v2/personal, /webhooks/waha-v2/business
+ */
+export const WAHA_V2_WEBHOOK_BASE = "/webhooks/waha-v2" as const;
+/** @deprecated Use WAHA_V2_WEBHOOK_BASE */
+export const WAHA_V2_WEBHOOK_PATH = WAHA_V2_WEBHOOK_BASE;
+
+// ---------------------------------------------------------------------------
+// Resolved account — what the channel plugin operates on at runtime
+// ---------------------------------------------------------------------------
+
+export type ResolvedWahaV2Account = {
+  accountId: string;
+  name?: string;
+  baseUrl: string;
+  apiKey: string;
+  session: string;
+  /** Full public URL for WAHA to POST inbound events to. Optional — user must set this. */
+  webhookUrl?: string;
+  enabled: boolean;
+  dmPolicy?: string;
+  groupPolicy?: string;
+  debounceMs?: number;
+  allowFrom?: string[];
+  allowGroups?: string[];
+  pauseOnOwnerMessage?: boolean;
+  ownerPauseWords?: string[];
+  ownerResumeWords?: string[];
+  typing?: WahaV2TypingConfig;
+  labelRouting?: WahaV2LabelRoutingConfig;
+};
+
+// ---------------------------------------------------------------------------
+// WAHA webhook event payload — structure common across WEBJS / NOWEB / GOWS
+// ---------------------------------------------------------------------------
+
+export type WahaV2MediaInfo = {
+  url?: string;
+  mimetype?: string;
+  filename?: string;
+  /** Base64-encoded data (some engines embed it directly). */
+  data?: string;
+};
+
+export type WahaV2WebhookPayload = {
+  id?: string;
+  from?: string;
+  to?: string;
+  body?: string;
+  type?: string;
+  fromMe?: boolean;
+  isGroupMsg?: boolean;
+  hasMedia?: boolean;
+  /** Can be a plain string or WEBJS-style `{ _serialized: "..." }` object. */
+  chatId?: string | { _serialized?: string };
+  timestamp?: number;
+  /** Present when type is image / video / audio / document / ptt. */
+  media?: WahaV2MediaInfo;
+  /** Some engines embed media info under _data. */
+  _data?: { media?: WahaV2MediaInfo; body?: string } & Record<string, unknown>;
+};
+
+export type WahaV2WebhookEvent = {
+  event: string;
+  session: string;
+  payload?: WahaV2WebhookPayload;
+};
+
+// ---------------------------------------------------------------------------
+// Typed API responses (replaces waha-node's pervasive `any`)
+// ---------------------------------------------------------------------------
+
+export type WahaV2MessageResult = {
+  id?: string;
+  _serialized?: string;
+};
+
+export type WahaV2SessionInfo = {
+  name?: string;
+  status?: string;
+};
+
+export type WahaV2ProbeResult = {
+  ok: boolean;
+  status?: string;
+  error?: string;
+};