@lofa199419/waha-v2 2.1.0

package/src/webhook.ts

@@ -0,0 +1,841 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { homedir } from "node:os";
+import { extname, join } from "node:path";
+import { readJsonBodyWithLimit, sleep } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { resolveWahaV2Account, resolveWahaV2AccountBySession } from "./accounts.js";
+import { calcTypingDelayMs, chunkWahaMessage } from "./deliver.js";
+import { getWahaV2Logger, getWahaV2Runtime, requireWahaV2Client } from "./runtime.js";
+import {
+  WAHA_V2_CHANNEL_ID,
+  type WahaV2MediaInfo,
+  type WahaV2WebhookEvent,
+  type WahaV2WebhookPayload,
+} from "./types.js";
+
+const WA_STATUS_CHAT_ID = "status@broadcast";
+const LABEL_CACHE_DEFAULT_TTL_SEC = 120;
+const labelCache = new Map<string, { expiresAt: number; labels: Array<{ id?: string; name?: string }> }>();
+const sessionLabelCache = new Map<
+  string,
+  { expiresAt: number; labels: Array<{ id?: string; name?: string; color?: number; colorHex?: string }> }
+>();
+type PauseReason = "owner-message" | "owner-word";
+const manuallyPausedChats = new Map<string, { reason: PauseReason; updatedAt: number }>();
+type PendingInboundEvent = { event: WahaV2WebhookEvent; cfg: OpenClawConfig; accountId?: string };
+const inboundDebouncerByAccount = new Map<
+  string,
+  {
+    debounceMs: number;
+    enqueue: (item: PendingInboundEvent) => Promise<void>;
+  }
+>();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** WAHA chatId can be a plain string or `{ _serialized: "..." }` (WEBJS engine). */
+function parseChatId(chatId: WahaV2WebhookPayload["chatId"]): string | undefined {
+  if (!chatId) return undefined;
+  if (typeof chatId === "string") return chatId;
+  return chatId._serialized;
+}
+
+function normalizeChatId(value: string): string {
+  return String(value ?? "").trim().toLowerCase();
+}
+
+function pausedChatKey(accountId: string, chatId: string): string {
+  return `${accountId}:${normalizeChatId(chatId)}`;
+}
+
+function isStatusBroadcastId(value: string | undefined): boolean {
+  return String(value ?? "")
+    .trim()
+    .toLowerCase() === WA_STATUS_CHAT_ID;
+}
+
+function resolveLabelRoutingInstruction(
+  labels: Array<{ id?: string; name?: string }>,
+  routing:
+    | {
+        enabled?: boolean;
+        defaultInstruction?: string;
+        rules?: Array<{ match: string; instruction: string; by?: "name" | "id" }>;
+      }
+    | undefined,
+): string | undefined {
+  if (!routing) return undefined;
+  if (routing.enabled === false) return undefined;
+
+  const rules = Array.isArray(routing.rules) ? routing.rules : [];
+  const names = new Set(
+    labels
+      .map((l) => String(l?.name ?? "").trim().toLowerCase())
+      .filter(Boolean),
+  );
+  const ids = new Set(
+    labels
+      .map((l) => String(l?.id ?? "").trim())
+      .filter(Boolean),
+  );
+
+  for (const rule of rules) {
+    const match = String(rule?.match ?? "").trim();
+    const instruction = String(rule?.instruction ?? "").trim();
+    if (!match || !instruction) continue;
+    if (rule.by === "id") {
+      if (ids.has(match)) return instruction;
+      continue;
+    }
+    if (names.has(match.toLowerCase())) return instruction;
+  }
+
+  const fallback = String(routing.defaultInstruction ?? "").trim();
+  return fallback || undefined;
+}
+
+function hasMatchingPauseLabel(
+  labels: Array<{ id?: string; name?: string }>,
+  pauseLabels?: string[],
+): string | undefined {
+  const wanted = new Set(
+    (pauseLabels ?? [])
+      .map((entry) => String(entry).trim().toLowerCase())
+      .filter(Boolean),
+  );
+  if (wanted.size === 0) return undefined;
+
+  for (const label of labels) {
+    const name = String(label.name ?? "")
+      .trim()
+      .toLowerCase();
+    const id = String(label.id ?? "").trim().toLowerCase();
+    if (name && wanted.has(name)) return label.name ?? label.id ?? name;
+    if (id && wanted.has(id)) return label.name ?? label.id ?? id;
+  }
+  return undefined;
+}
+
+async function getChatLabelsCached(
+  client: ReturnType<typeof requireWahaV2Client>,
+  accountId: string,
+  session: string,
+  chatId: string,
+  cacheTtlSec?: number,
+): Promise<Array<{ id?: string; name?: string }>> {
+  const ttlSec = Math.max(0, Math.floor(cacheTtlSec ?? LABEL_CACHE_DEFAULT_TTL_SEC));
+  const cacheKey = `${accountId}:${session}:${chatId}`;
+  const now = Date.now();
+  const cached = labelCache.get(cacheKey);
+  if (cached && cached.expiresAt > now) {
+    return cached.labels;
+  }
+  const labels = await client.getChatLabels(session, chatId);
+  if (ttlSec > 0) {
+    labelCache.set(cacheKey, { labels, expiresAt: now + ttlSec * 1000 });
+  } else {
+    labelCache.delete(cacheKey);
+  }
+  return labels;
+}
+
+async function getPauseLabelMatch(
+  client: ReturnType<typeof requireWahaV2Client>,
+  account: {
+    accountId: string;
+    session: string;
+    labelRouting?: { cacheTtlSec?: number; pauseLabels?: string[] };
+  },
+  chatId: string,
+  forceFresh = false,
+): Promise<string | undefined> {
+  const pauseLabels = account.labelRouting?.pauseLabels;
+  if (!pauseLabels || pauseLabels.length === 0) return undefined;
+  const labels = await getChatLabelsCached(
+    client,
+    account.accountId,
+    account.session,
+    chatId,
+    forceFresh ? 0 : account.labelRouting?.cacheTtlSec,
+  );
+  return hasMatchingPauseLabel(labels, pauseLabels);
+}
+
+async function getSessionLabelsCached(
+  client: ReturnType<typeof requireWahaV2Client>,
+  accountId: string,
+  session: string,
+  cacheTtlSec?: number,
+): Promise<Array<{ id?: string; name?: string; color?: number; colorHex?: string }>> {
+  const ttlSec = Math.max(0, Math.floor(cacheTtlSec ?? LABEL_CACHE_DEFAULT_TTL_SEC));
+  const cacheKey = `${accountId}:${session}`;
+  const now = Date.now();
+  const cached = sessionLabelCache.get(cacheKey);
+  if (cached && cached.expiresAt > now) {
+    return cached.labels;
+  }
+  const labels = await client.listLabels(session);
+  if (ttlSec > 0) {
+    sessionLabelCache.set(cacheKey, { labels, expiresAt: now + ttlSec * 1000 });
+  } else {
+    sessionLabelCache.delete(cacheKey);
+  }
+  return labels;
+}
+
+function extractLabelDirectives(text: string): { cleanText: string; labels: string[] } {
+  const labels: string[] = [];
+  const cleanText = text.replace(/\[\[LABEL:([^[\]]+)\]\]/gi, (_full, value: string) => {
+    const label = String(value ?? "").trim();
+    if (label) labels.push(label);
+    return "";
+  });
+  const uniqueLabels = Array.from(new Set(labels.map((l) => l.toLowerCase()))).map((lower) => {
+    const original = labels.find((l) => l.toLowerCase() === lower);
+    return original ?? lower;
+  });
+  return { cleanText, labels: uniqueLabels };
+}
+
+async function applyLabelDirectivesToChat(
+  client: ReturnType<typeof requireWahaV2Client>,
+  account: {
+    accountId: string;
+    session: string;
+    labelRouting?: { cacheTtlSec?: number };
+  },
+  chatId: string,
+  directives: string[],
+): Promise<void> {
+  if (directives.length === 0) return;
+  const allLabels = await getSessionLabelsCached(
+    client,
+    account.accountId,
+    account.session,
+    account.labelRouting?.cacheTtlSec,
+  );
+  const targets: Array<{ id: string; name?: string }> = [];
+  for (const directive of directives) {
+    const wanted = String(directive ?? "").trim();
+    if (!wanted) continue;
+    const wantedLc = wanted.toLowerCase();
+    const found = allLabels.find((l) => {
+      const byName = String(l.name ?? "")
+        .trim()
+        .toLowerCase();
+      const byId = String(l.id ?? "").trim();
+      return byName === wantedLc || byId === wanted;
+    });
+    if (!found?.id) {
+      getWahaV2Logger().warn(`waha-v2: label directive not found "${wanted}" (${chatId})`);
+      continue;
+    }
+    targets.push({ id: String(found.id), name: found.name });
+  }
+  if (targets.length === 0) return;
+
+  const currentLabels = await getChatLabelsCached(
+    client,
+    account.accountId,
+    account.session,
+    chatId,
+    account.labelRouting?.cacheTtlSec,
+  );
+  const mergedIds = new Set(currentLabels.map((l) => String(l.id ?? "").trim()).filter(Boolean));
+  let changed = false;
+  for (const target of targets) {
+    if (!mergedIds.has(target.id)) {
+      mergedIds.add(target.id);
+      changed = true;
+    }
+  }
+  if (!changed) return;
+
+  const nextIds = Array.from(mergedIds);
+  await client.setChatLabels(account.session, chatId, nextIds);
+
+  const nextLabels = [...currentLabels];
+  for (const target of targets) {
+    if (!nextLabels.some((l) => String(l.id ?? "").trim() === target.id)) {
+      nextLabels.push({ id: target.id, name: target.name });
+    }
+  }
+  const ttlSec = Math.max(
+    0,
+    Math.floor(account.labelRouting?.cacheTtlSec ?? LABEL_CACHE_DEFAULT_TTL_SEC),
+  );
+  const cacheKey = `${account.accountId}:${account.session}:${chatId}`;
+  if (ttlSec > 0) {
+    labelCache.set(cacheKey, { labels: nextLabels, expiresAt: Date.now() + ttlSec * 1000 });
+  } else {
+    labelCache.delete(cacheKey);
+  }
+
+  getWahaV2Logger().info(
+    `waha-v2: applied label directives (${chatId}): ${targets.map((t) => t.name ?? t.id).join(", ")}`,
+  );
+}
+
+/** Normalize E.164-ish numbers to `<digits>@c.us`. */
+function normalizeSenderId(raw: string): string {
+  if (raw.includes("@")) return raw;
+  return `${raw.replace(/\D+/g, "")}@c.us`;
+}
+
+function matchesOwnerPauseWord(text: string, words?: string[]): string | undefined {
+  const normalized = String(text ?? "").trim().toLowerCase();
+  if (!normalized) return undefined;
+  return words?.find((entry) => entry.trim().toLowerCase() === normalized);
+}
+
+function matchesOwnerResumeWord(text: string, words?: string[]): string | undefined {
+  const normalized = String(text ?? "").trim().toLowerCase();
+  if (!normalized) return undefined;
+  return words?.find((entry) => entry.trim().toLowerCase() === normalized);
+}
+
+/** Map MIME type to a file extension. */
+function mimeToExt(mime: string): string {
+  const map: Record<string, string> = {
+    "image/jpeg": ".jpg",
+    "image/png": ".png",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+    "video/mp4": ".mp4",
+    "video/webm": ".webm",
+    "audio/ogg": ".ogg",
+    "audio/mpeg": ".mp3",
+    "audio/mp4": ".m4a",
+    "audio/webm": ".webm",
+    "audio/ogg; codecs=opus": ".ogg",
+    "application/pdf": ".pdf",
+  };
+  const base = mime.split(";")[0]?.trim() ?? mime;
+  return map[base] ?? map[mime] ?? ".bin";
+}
+
+/** Human-readable media type label for BodyForAgent. */
+function mediaTypeLabel(type?: string, mime?: string): string {
+  if (type === "ptt" || type === "audio" || mime?.startsWith("audio/")) return "voice message";
+  if (type === "image" || mime?.startsWith("image/")) return "image";
+  if (type === "video" || mime?.startsWith("video/")) return "video";
+  if (type === "document") return "document";
+  if (type === "sticker") return "sticker";
+  return "media file";
+}
+
+/**
+ * Resolve inbound media to a local temp file path.
+ * Tries base64 `data` first (already embedded), then downloads from `url`.
+ * Returns the temp file path and MIME type, or undefined if no media.
+ */
+async function resolveInboundMedia(
+  media: WahaV2MediaInfo,
+  accountId: string,
+): Promise<{ path: string; mimeType: string } | undefined> {
+  const client = requireWahaV2Client(accountId);
+  let buffer: Buffer | undefined;
+  let mimeType = media.mimetype ?? "application/octet-stream";
+
+  if (media.data) {
+    // Some engines embed base64 data directly in the webhook payload.
+    buffer = Buffer.from(media.data, "base64");
+  } else if (media.url) {
+    try {
+      const downloaded = await client.downloadMediaBuffer(media.url);
+      buffer = downloaded.buffer;
+      // Prefer server-reported content-type over the webhook field.
+      if (downloaded.contentType && downloaded.contentType !== "application/octet-stream") {
+        mimeType = downloaded.contentType;
+      }
+    } catch (err) {
+      getWahaV2Logger().warn(`waha-v2: media download failed (${media.url}): ${String(err)}`);
+      return undefined;
+    }
+  }
+
+  if (!buffer || buffer.length === 0) return undefined;
+
+  // Pick a filename: use original or derive from MIME type.
+  const origExt = media.filename ? extname(media.filename) : "";
+  const ext = origExt || mimeToExt(mimeType);
+
+  // Store inbound media under ~/.openclaw so image tools with workspace-only
+  // allowlists can still access files after a safe copy/link into workspace.
+  const mediaDir = join(homedir(), ".openclaw", "media", "waha-v2");
+  await mkdir(mediaDir, { recursive: true });
+
+  const tmpPath = join(mediaDir, `openclaw-waha-v2-${randomUUID()}${ext}`);
+  await writeFile(tmpPath, buffer);
+  return { path: tmpPath, mimeType };
+}
+
+// ---------------------------------------------------------------------------
+// Policy helpers
+// ---------------------------------------------------------------------------
+
+/** Case-insensitive allowFrom check. Returns true when the list is empty (open). */
+
+/** Normalize group id to <id>@g.us (best-effort). */
+function normalizeGroupId(raw: string): string {
+  const t = String(raw ?? "").trim().toLowerCase();
+  if (!t) return "";
+  if (t.endsWith("@g.us")) return t;
+  if (t.includes("@")) return t;
+  return `${t}@g.us`;
+}
+
+/** Group allowlist check for groupPolicy=allowlist. */
+function isGroupAllowed(chatId: string, allowGroups: Array<string | number>): boolean {
+  const list = allowGroups.map((e) => normalizeGroupId(String(e))).filter(Boolean);
+  if (list.length === 0) return false;
+  if (list.includes("*")) return true;
+  return list.includes(normalizeGroupId(chatId));
+}
+function isSenderAllowed(senderId: string, allowFrom: Array<string | number>): boolean {
+  const list = allowFrom.map((e) => String(e).trim().toLowerCase()).filter(Boolean);
+  if (list.length === 0) return true;
+  if (list.includes("*")) return true;
+  return list.includes(senderId.trim().toLowerCase());
+}
+
+// ---------------------------------------------------------------------------
+// Inbound event processor (runs async, after 200 is sent)
+// ---------------------------------------------------------------------------
+
+async function processWahaV2EventImmediate(
+  event: WahaV2WebhookEvent,
+  cfg: OpenClawConfig,
+  accountId?: string,
+): Promise<void> {
+  const core = getWahaV2Runtime();
+  const eventName = String(event.event ?? "").trim().toLowerCase();
+
+  if (eventName !== "message" && eventName !== "message.any") return;
+
+  // Find the account that owns this session.
+  const account = accountId
+    ? resolveWahaV2Account(cfg, accountId)
+    : (resolveWahaV2AccountBySession(cfg, event.session) ?? resolveWahaV2Account(cfg, undefined));
+
+  const payload = event.payload;
+  if (!payload) return;
+
+  const text = payload.body?.trim() ?? payload._data?.body?.trim() ?? "";
+  const isGroup = Boolean(payload.isGroupMsg);
+  const senderId = payload.from ? normalizeSenderId(payload.from) : "";
+  const chatId = parseChatId(payload.chatId) ?? senderId;
+  const pausedKey = pausedChatKey(account.accountId, chatId);
+
+  // Hard-drop WhatsApp Status/Stories pseudo-thread before any session writes.
+  if (isStatusBroadcastId(chatId) || isStatusBroadcastId(senderId)) return;
+
+  if (payload.fromMe) {
+    const matchedResumeWord = matchesOwnerResumeWord(text, account.ownerResumeWords);
+    if (matchedResumeWord) {
+      const hadManualPause = manuallyPausedChats.delete(pausedKey);
+      getWahaV2Logger().info(
+        hadManualPause
+          ? `waha-v2: resumed chat ${chatId} for account "${account.accountId}" via owner word "${matchedResumeWord}"`
+          : `waha-v2: owner resume word "${matchedResumeWord}" received for unpaused chat ${chatId} on account "${account.accountId}"`,
+      );
+      return;
+    }
+
+    const matchedPauseWord = matchesOwnerPauseWord(text, account.ownerPauseWords);
+    if (matchedPauseWord) {
+      manuallyPausedChats.set(pausedKey, { reason: "owner-word", updatedAt: Date.now() });
+      getWahaV2Logger().info(
+        `waha-v2: paused chat ${chatId} for account "${account.accountId}" via owner word "${matchedPauseWord}"`,
+      );
+    } else if (account.pauseOnOwnerMessage) {
+      manuallyPausedChats.set(pausedKey, { reason: "owner-message", updatedAt: Date.now() });
+      getWahaV2Logger().info(
+        `waha-v2: paused chat ${chatId} for account "${account.accountId}" via owner message`,
+      );
+    }
+    return;
+  }
+
+  // Resolve media from the payload (checking both top-level and _data).
+  const rawMedia: WahaV2MediaInfo | undefined = payload.media ?? payload._data?.media;
+  const hasMedia = Boolean(payload.hasMedia || rawMedia);
+
+  // Skip if no text and no media — nothing to dispatch.
+  if (!text && !hasMedia) return;
+
+  // Apply inbound access policies before dispatching to the agent runtime.
+  if (isGroup) {
+    if (account.groupPolicy === "deny") return;
+    if (account.groupPolicy === "allowlist" && !isGroupAllowed(chatId, account.allowGroups ?? [])) {
+      return;
+    }
+  } else {
+    if (account.dmPolicy === "deny") return;
+    if (!isSenderAllowed(senderId, account.allowFrom ?? [])) return;
+  }
+
+  const client = requireWahaV2Client(account.accountId);
+
+  const manualPause = manuallyPausedChats.get(pausedKey);
+  if (manualPause) {
+    getWahaV2Logger().info(
+      `waha-v2: skipped inbound message for paused chat ${chatId} on account "${account.accountId}" (${manualPause.reason})`,
+    );
+    return;
+  }
+
+  const pauseLabelMatch = await getPauseLabelMatch(client, account, chatId);
+  if (pauseLabelMatch) {
+    getWahaV2Logger().info(
+      `waha-v2: skipped inbound message for paused chat ${chatId} on account "${account.accountId}" via label "${pauseLabelMatch}"`,
+    );
+    return;
+  }
+
+  let policyInstruction: string | undefined;
+  let labelSummary = "none";
+  if (account.labelRouting) {
+    try {
+      const labels = await getChatLabelsCached(
+        client,
+        account.accountId,
+        account.session,
+        chatId,
+        account.labelRouting.cacheTtlSec,
+      );
+
+      if (labels.length > 0) {
+        labelSummary = labels.map((l) => l.name || l.id || "?").join(", ");
+      }
+      policyInstruction = resolveLabelRoutingInstruction(labels, account.labelRouting);
+    } catch (err) {
+      getWahaV2Logger().warn(`waha-v2: label lookup failed (${chatId}): ${String(err)}`);
+    }
+  }
+
+  // Download/decode media to a local temp file so the agent can inspect it.
+  let mediaPath: string | undefined;
+  let mediaMime: string | undefined;
+  if (hasMedia && rawMedia) {
+    const resolved = await resolveInboundMedia(rawMedia, account.accountId).catch((err) => {
+      getWahaV2Logger().warn(`waha-v2: media resolution error: ${String(err)}`);
+      return undefined;
+    });
+    mediaPath = resolved?.path;
+    mediaMime = resolved?.mimeType;
+  }
+
+  // Build a descriptive body when there's media but no caption text.
+  const mediaLabel = mediaPath ? mediaTypeLabel(payload.type, mediaMime) : undefined;
+  const bodyForAgent = text || (mediaLabel ? `[${mediaLabel}]` : "");
+  const policyPrefix = policyInstruction
+    ? `[CHAT POLICY]\nLabels: ${labelSummary}\nInstruction: ${policyInstruction}\n\n`
+    : "";
+  const bodyForAgentWithPolicy = `${policyPrefix}${bodyForAgent}`.trim();
+
+  // If we have both caption text and media, surface both in Body.
+  const combinedBody = text && mediaLabel ? `${text}\n[${mediaLabel}]` : bodyForAgent;
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg,
+    channel: WAHA_V2_CHANNEL_ID,
+    accountId: account.accountId,
+    peer: { kind: isGroup ? "group" : "direct", id: chatId },
+  });
+
+  const storePath = core.channel.session.resolveStorePath(cfg.session?.store, {
+    agentId: route.agentId,
+  });
+
+  const ctx = core.channel.reply.finalizeInboundContext({
+    Body: combinedBody,
+    BodyForAgent: bodyForAgentWithPolicy,
+    RawBody: text,
+    CommandBody: text,
+    From: `${WAHA_V2_CHANNEL_ID}:${senderId}`,
+    To: `${WAHA_V2_CHANNEL_ID}:${account.session}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: isGroup ? ("group" as const) : ("direct" as const),
+    Provider: WAHA_V2_CHANNEL_ID,
+    Surface: WAHA_V2_CHANNEL_ID,
+    SenderId: senderId,
+    MessageSid: payload.id,
+    Timestamp: payload.timestamp ? payload.timestamp * 1000 : Date.now(),
+    // Media fields — consumed by the agent framework to send the file to the AI.
+    MediaUrl: mediaPath,
+    MediaPath: mediaPath,
+    MediaType: mediaMime,
+    MediaUrls: mediaPath ? [mediaPath] : undefined,
+    MediaPaths: mediaPath ? [mediaPath] : undefined,
+    MediaTypes: mediaMime ? [mediaMime] : undefined,
+  });
+
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctx.SessionKey ?? route.sessionKey,
+    ctx,
+    onRecordError: (err) => {
+      getWahaV2Logger().warn(`waha-v2: session record error: ${String(err)}`);
+    },
+  });
+
+  // Resolve typing/chunking config — all default to enabled/on.
+  const typingEnabled = account.typing?.enabled !== false;
+  const chunkingEnabled = account.typing?.chunking !== false;
+  const charsPerSecond = account.typing?.charsPerSecond;
+  const maxChunkLength = account.typing?.maxChunkLength;
+  const deliveryDebugEnabled = account.typing?.debug === true;
+  const seenDelayMs = 3000;
+  const seenMessageIds = payload.id ? [String(payload.id)] : undefined;
+  let preReplyTypingStarted = false;
+
+  const logDeliveryDebug = (message: string): void => {
+    if (!deliveryDebugEnabled) return;
+    getWahaV2Logger().info(`[waha-v2 delivery] ${new Date().toISOString()} ${message}`);
+  };
+
+  const startTypingWithLog = async (phase: string): Promise<void> => {
+    if (!typingEnabled) return;
+    await client.startTyping(account.session, chatId);
+    logDeliveryDebug(`${phase}: started typing`);
+  };
+
+  const stopTypingWithLog = async (phase: string): Promise<void> => {
+    if (!typingEnabled) return;
+    await client.stopTyping(account.session, chatId);
+    logDeliveryDebug(`${phase}: stopped typing`);
+  };
+
+  const preReplySequencePromise = (async () => {
+    logDeliveryDebug(`queued to agent for ${chatId}`);
+    await sleep(seenDelayMs);
+    await client.sendSeen(account.session, chatId, seenMessageIds);
+    logDeliveryDebug(`marked seen after ${seenDelayMs}ms for ${chatId}`);
+    if (typingEnabled) {
+      await startTypingWithLog("pre-output");
+      preReplyTypingStarted = true;
+    }
+  })().catch((err) => {
+    getWahaV2Logger().warn(`waha-v2: pre-reply sequence failed (${chatId}): ${String(err)}`);
+  });
+
+  const { dispatcher, replyOptions, markDispatchIdle } =
+    core.channel.reply.createReplyDispatcherWithTyping({
+      typingCallbacks: undefined,
+      humanDelay: undefined,
+      deliver: async (replyPayload) => {
+        await preReplySequencePromise;
+        const manualPause = manuallyPausedChats.get(pausedKey);
+        if (manualPause) {
+          getWahaV2Logger().info(
+            `waha-v2: dropping reply for paused chat ${chatId} on account "${account.accountId}" (${manualPause.reason})`,
+          );
+          return;
+        }
+
+        const sendPauseLabelMatch = await getPauseLabelMatch(client, account, chatId, true);
+        if (sendPauseLabelMatch) {
+          getWahaV2Logger().info(
+            `waha-v2: dropping reply for paused chat ${chatId} on account "${account.accountId}" via label "${sendPauseLabelMatch}"`,
+          );
+          return;
+        }
+
+        const rawReplyText = replyPayload.text?.trim() ?? "";
+        if (!rawReplyText) return;
+
+        const { cleanText, labels: labelDirectives } = extractLabelDirectives(rawReplyText);
+        if (labelDirectives.length > 0) {
+          await applyLabelDirectivesToChat(client, account, chatId, labelDirectives).catch((err) => {
+            getWahaV2Logger().warn(
+              `waha-v2: failed applying label directives (${chatId}): ${String(err)}`,
+            );
+          });
+        }
+
+        const replyText = cleanText.trim();
+        if (!replyText) return;
+
+        const chunks = chunkingEnabled ? chunkWahaMessage(replyText, maxChunkLength) : [replyText];
+        logDeliveryDebug(
+          `output ready for ${chatId}; chunking=${chunkingEnabled} chunks=${chunks.length} totalLen=${replyText.length}`,
+        );
+
+        if (preReplyTypingStarted) {
+          await stopTypingWithLog("pre-output");
+          preReplyTypingStarted = false;
+        }
+
+        if (!chunkingEnabled || chunks.length <= 1) {
+          getWahaV2Logger().debug?.(
+            `waha-v2: send single reply (${chatId}) len=${replyText.length}`,
+          );
+          await client.sendText(account.session, chatId, chunks[0] ?? replyText);
+          logDeliveryDebug(`sent single reply for ${chatId}`);
+          return;
+        }
+        getWahaV2Logger().debug?.(
+          `waha-v2: send chunked reply (${chatId}) chunks=${chunks.length} totalLen=${replyText.length}`,
+        );
+        for (let i = 0; i < chunks.length; i++) {
+          const chunkManualPause = manuallyPausedChats.get(pausedKey);
+          if (chunkManualPause) {
+            getWahaV2Logger().info(
+              `waha-v2: stopping chunked reply for paused chat ${chatId} on account "${account.accountId}" (${chunkManualPause.reason})`,
+            );
+            return;
+          }
+
+          const chunkPauseLabelMatch = await getPauseLabelMatch(client, account, chatId, true);
+          if (chunkPauseLabelMatch) {
+            getWahaV2Logger().info(
+              `waha-v2: stopping chunked reply for paused chat ${chatId} on account "${account.accountId}" via label "${chunkPauseLabelMatch}"`,
+            );
+            return;
+          }
+
+          const chunk = chunks[i];
+          if (!chunk) continue;
+          if (i > 0 && typingEnabled) {
+            try {
+              await startTypingWithLog(`chunk ${i + 1}/${chunks.length}`);
+              await sleep(calcTypingDelayMs(chunk, charsPerSecond));
+              await stopTypingWithLog(`chunk ${i + 1}/${chunks.length}`);
+            } catch (err) {
+              getWahaV2Logger().warn(
+                `waha-v2: inter-chunk typing failed (${chatId}, ${i + 1}/${chunks.length}): ${String(err)}`,
+              );
+            }
+          }
+          getWahaV2Logger().debug?.(
+            `waha-v2: send chunk (${chatId}) index=${i + 1}/${chunks.length} len=${chunk.length}`,
+          );
+          await client.sendText(account.session, chatId, chunk);
+          logDeliveryDebug(`sent chunk ${i + 1}/${chunks.length} for ${chatId} len=${chunk.length}`);
+        }
+      },
+    });
+
+  try {
+    await core.channel.reply.dispatchReplyFromConfig({ ctx, cfg, dispatcher, replyOptions });
+  } finally {
+    await preReplySequencePromise;
+    if (preReplyTypingStarted) {
+      try {
+        await stopTypingWithLog("finalize");
+      } catch (err) {
+        getWahaV2Logger().warn(`waha-v2: final typing stop failed (${chatId}): ${String(err)}`);
+      } finally {
+        preReplyTypingStarted = false;
+      }
+    }
+    markDispatchIdle();
+  }
+}
+
+async function handleWahaV2Event(
+  event: WahaV2WebhookEvent,
+  cfg: OpenClawConfig,
+  accountId?: string,
+): Promise<void> {
+  const core = getWahaV2Runtime();
+  const account = accountId
+    ? resolveWahaV2Account(cfg, accountId)
+    : (resolveWahaV2AccountBySession(cfg, event.session) ?? resolveWahaV2Account(cfg, undefined));
+  const debounceMs = core.channel.debounce.resolveInboundDebounceMs({
+    cfg,
+    channel: WAHA_V2_CHANNEL_ID,
+    overrideMs: account.debounceMs,
+  });
+
+  if (debounceMs <= 0) {
+    await processWahaV2EventImmediate(event, cfg, accountId);
+    return;
+  }
+
+  const debouncerKey = account.accountId || "default";
+  const existing = inboundDebouncerByAccount.get(debouncerKey);
+  if (!existing || existing.debounceMs !== debounceMs) {
+    const debouncer = core.channel.debounce.createInboundDebouncer<PendingInboundEvent>({
+      debounceMs,
+      buildKey: (item) => {
+        const payload = item.event.payload;
+        const sender = payload?.from ? normalizeSenderId(payload.from) : "";
+        const chatId = parseChatId(payload?.chatId) ?? sender;
+        if (!chatId) return null;
+        return `${item.event.session}:${chatId}`;
+      },
+      shouldDebounce: (item) => {
+        const payload = item.event.payload;
+        if (!payload || payload.fromMe) return false;
+        const hasMedia = Boolean(payload.hasMedia || payload.media || payload._data?.media);
+        return !hasMedia;
+      },
+      onFlush: async (items) => {
+        const last = items[items.length - 1];
+        if (!last) return;
+        await processWahaV2EventImmediate(last.event, last.cfg, last.accountId);
+      },
+      onError: (err) => {
+        getWahaV2Logger().warn(`waha-v2: inbound debounce flush error: ${String(err)}`);
+      },
+    });
+    inboundDebouncerByAccount.set(debouncerKey, { debounceMs, enqueue: debouncer.enqueue });
+  }
+
+  await inboundDebouncerByAccount.get(debouncerKey)?.enqueue({ event, cfg, accountId });
+}
+
+// ---------------------------------------------------------------------------
+// HTTP handler — registered via api.registerHttpHandler
+// ---------------------------------------------------------------------------
+
+/**
+ * Handles inbound WAHA webhook POSTs.
+ * Responds 200 immediately, then processes the event asynchronously.
+ */
+export async function handleWahaV2WebhookRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  cfg: OpenClawConfig,
+  /** accountId extracted from the URL path — makes routing unambiguous. */
+  accountId?: string,
+): Promise<void> {
+  if (req.method !== "POST") {
+    res.statusCode = 405;
+    res.end("Method Not Allowed");
+    return;
+  }
+
+  const body = await readJsonBodyWithLimit(req, {
+    maxBytes: 10 * 1024 * 1024, // 10 MB — some engines embed base64 media in webhook body
+    timeoutMs: 30_000,
+    emptyObjectOnEmpty: true,
+  });
+
+  if (!body.ok) {
+    res.statusCode = body.code === "PAYLOAD_TOO_LARGE" ? 413 : 400;
+    res.end(body.error ?? "Bad Request");
+    return;
+  }
+
+  // Acknowledge immediately — WAHA expects a fast 200.
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end('{"ok":true}');
+
+  // Process asynchronously so WAHA's retry logic isn't triggered by agent latency.
+  handleWahaV2Event(body.value as WahaV2WebhookEvent, cfg, accountId).catch((err) => {
+    try {
+      getWahaV2Logger().warn(`waha-v2 webhook error: ${String(err)}`);
+    } catch {
+      // Runtime may not be initialized in edge cases; swallow.
+    }
+  });
+}