@daolmedo/openclaw-twilio-whatsapp 1.1.25 → 1.1.27

package/dist/index.js

@@ -2,13 +2,13 @@
 import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
 
 // src/accounts.ts
-var getChannelConfig = (cfg) => cfg.channels && cfg.channels["twilio-whatsapp"] ? cfg.channels["twilio-whatsapp"] : void 0;
+var getTwilioChannelConfig = (cfg) => cfg.channels && cfg.channels["twilio-whatsapp"] ? cfg.channels["twilio-whatsapp"] : void 0;
 function listTwilioAccountIds(cfg) {
-  const ch = getChannelConfig(cfg);
+  const ch = getTwilioChannelConfig(cfg);
   return Object.keys(ch?.accounts ?? {});
 }
 function resolveTwilioAccount(cfg, accountId) {
-  const ch = getChannelConfig(cfg);
+  const ch = getTwilioChannelConfig(cfg);
   const id = accountId ?? "default";
   const entry = ch?.accounts?.[id];
   if (!entry) {
@@ -24,7 +24,7 @@ function resolveTwilioAccount(cfg, accountId) {
   };
 }
 function findTwilioAccountByPhoneNumber(cfg, phoneNumber) {
-  const ch = getChannelConfig(cfg);
+  const ch = getTwilioChannelConfig(cfg);
   if (!ch?.accounts) return void 0;
   for (const [id, entry] of Object.entries(ch.accounts)) {
     const normalized = normalizePhoneNumber(entry.phoneNumber);
@@ -171,9 +171,7 @@ var twilioWhatsappPlugin = {
     selectionLabel: "WhatsApp (Twilio)",
     docsPath: "/channels/twilio-whatsapp",
     blurb: "WhatsApp messaging via Twilio Business API",
-    markdownCapable: false,
-    showInSetup: true,
-    showConfigured: true
+    markdownCapable: false
   },
   capabilities: {
     chatTypes: ["direct"],
@@ -204,16 +202,9 @@ var twilioWhatsappPlugin = {
     async startAccount(ctx) {
       const account = ctx.account;
       const phoneNumber = normalizePhoneNumber(account.phoneNumber);
-      if (!ctx.channelRuntime) {
-        console.error(
-          `[twilio-whatsapp] channelRuntime not provided for account ${ctx.accountId}. Inbound dispatch will not work.`
-        );
-        return;
-      }
       setRuntimeForPhoneNumber(phoneNumber, {
         cfg: ctx.cfg,
-        accountId: ctx.accountId,
-        channelRuntime: ctx.channelRuntime
+        accountId: ctx.accountId
       });
       ctx.setStatus({
         accountId: ctx.accountId,
@@ -243,9 +234,51 @@ var twilioWhatsappPlugin = {
 
 // src/http-routes.ts
 import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { dispatchInboundDirectDmWithRuntime } from "openclaw/plugin-sdk/direct-dm";
-import { saveMediaBuffer } from "openclaw/plugin-sdk/media-runtime";
+import * as path from "node:path";
+import { dispatchInboundDirectDmWithRuntime } from "openclaw/plugin-sdk/channel-inbound";
+import { saveMediaBuffer } from "openclaw/plugin-sdk/media-store";
+import {
+  createFixedWindowRateLimiter,
+  isRequestBodyLimitError,
+  readRequestBodyWithLimit
+} from "openclaw/plugin-sdk/webhook-ingress";
+
+// src/access.ts
+function normalizeAllowEntry(value) {
+  const raw = String(value).trim();
+  return raw === "*" ? raw : normalizePhoneNumber(raw);
+}
+function resolveTwilioInboundAccess(params) {
+  const policy = params.channelConfig?.dmPolicy ?? "pairing";
+  const sender = normalizePhoneNumber(params.senderPhone);
+  const entries = (params.channelConfig?.allowFrom ?? []).map(normalizeAllowEntry);
+  const hasSpecificMatch = entries.some((entry) => entry !== "*" && entry === sender);
+  const hasWildcard = entries.includes("*");
+  if (policy === "disabled") {
+    return { allowed: false, commandAuthorized: false, reason: "dmPolicy is disabled" };
+  }
+  if (policy === "open") {
+    return {
+      allowed: true,
+      // A public wildcard can admit conversation traffic, but must not grant
+      // privileged OpenClaw slash/control commands to every WhatsApp sender.
+      commandAuthorized: hasSpecificMatch,
+      reason: "dmPolicy is open"
+    };
+  }
+  if (hasSpecificMatch || hasWildcard) {
+    return {
+      allowed: true,
+      commandAuthorized: hasSpecificMatch,
+      reason: `${policy} sender matched allowFrom`
+    };
+  }
+  return {
+    allowed: false,
+    commandAuthorized: false,
+    reason: policy === "pairing" ? "pairing is required and this plugin has no paired sender entry" : "sender is not in allowFrom"
+  };
+}
 
 // src/webhook.ts
 import twilio2 from "twilio";
@@ -271,6 +304,7 @@ function parseTwilioWebhook(rawBody) {
     waId: p["WaId"] ?? "",
     profileName: p["ProfileName"] ?? "",
     messageSid: p["MessageSid"] ?? "",
+    accountSid: p["AccountSid"] ?? "",
     media,
     repliedToSid: p["OriginalRepliedMessageSid"]
   };
@@ -309,13 +343,84 @@ function startTypingKeepalive(opts) {
   };
 }
 
+// src/replay-cache.ts
+function createReplayCache(options) {
+  const entries = /* @__PURE__ */ new Map();
+  function prune(nowMs) {
+    for (const [key, expiresAt] of entries) {
+      if (expiresAt <= nowMs) entries.delete(key);
+    }
+    while (entries.size > options.maxEntries) {
+      const oldest = entries.keys().next().value;
+      if (oldest === void 0) break;
+      entries.delete(oldest);
+    }
+  }
+  return {
+    seen(key, nowMs = Date.now()) {
+      if (!key) return false;
+      const expiresAt = entries.get(key);
+      if (expiresAt !== void 0 && expiresAt > nowMs) return true;
+      entries.delete(key);
+      entries.set(key, nowMs + options.ttlMs);
+      prune(nowMs);
+      return false;
+    },
+    clear() {
+      entries.clear();
+    },
+    size() {
+      return entries.size;
+    }
+  };
+}
+
 // src/http-routes.ts
 var MEDIA_MAX_BYTES = 16 * 1024 * 1024;
+var WEBHOOK_MAX_BODY_BYTES = 128 * 1024;
+var webhookRateLimiter = createFixedWindowRateLimiter({
+  windowMs: 6e4,
+  maxRequests: 120,
+  maxTrackedKeys: 4096
+});
+var replayCache = createReplayCache({ ttlMs: 10 * 6e4, maxEntries: 1e4 });
+function twimlOk(res) {
+  res.writeHead(200, { "Content-Type": "text/xml; charset=utf-8" });
+  res.end('<?xml version="1.0" encoding="UTF-8"?><Response/>');
+}
+function twimlError(res, status, message) {
+  res.writeHead(status, { "Content-Type": "text/xml; charset=utf-8" });
+  res.end(
+    `<?xml version="1.0" encoding="UTF-8"?><Response><Message>${message}</Message></Response>`
+  );
+}
+function firstHeader(req, name) {
+  const value = req.headers[name.toLowerCase()];
+  return Array.isArray(value) ? value[0] ?? "" : value ?? "";
+}
+var pendingMediaByConversation = /* @__PURE__ */ new Map();
+var dispatchQueueByConversation = /* @__PURE__ */ new Map();
 function resolveMediaBatchFlushMs() {
   const raw = Number(process.env.TWILIO_WHATSAPP_MEDIA_BATCH_FLUSH_MS);
   if (Number.isFinite(raw) && raw >= 0) return Math.min(raw, 6e4);
   return 3e3;
 }
+function resolveMediaBatchInitialWaitMs() {
+  const rawValue = process.env.TWILIO_WHATSAPP_MEDIA_BATCH_INITIAL_WAIT_MS;
+  const raw = Number(rawValue);
+  if (rawValue !== void 0 && Number.isFinite(raw) && raw >= 0) {
+    return Math.min(raw, 6e4);
+  }
+  if (process.env.TWILIO_WHATSAPP_MEDIA_BATCH_FLUSH_MS !== void 0) {
+    return resolveMediaBatchFlushMs();
+  }
+  return 15e3;
+}
+function resolveMediaBatchMaxWaitMs() {
+  const raw = Number(process.env.TWILIO_WHATSAPP_MEDIA_BATCH_MAX_WAIT_MS);
+  if (Number.isFinite(raw) && raw >= 0) return Math.min(raw, 6e4);
+  return Math.min(resolveMediaBatchInitialWaitMs() + resolveMediaBatchFlushMs(), 6e4);
+}
 function resolveMediaBatchMaxItems() {
   const raw = Number(process.env.TWILIO_WHATSAPP_MEDIA_BATCH_MAX_ITEMS);
   if (Number.isFinite(raw) && raw > 0) return Math.floor(Math.min(raw, 50));
@@ -325,29 +430,15 @@ function summarizeText2(text) {
   if (!text) return "chars=0";
   return `chars=${text.length} preview=${JSON.stringify(text.slice(0, 120))}`;
 }
-async function readBody(req) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    req.on("data", (chunk) => chunks.push(chunk));
-    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
-    req.on("error", reject);
-  });
-}
-function twimlOk(res) {
-  res.writeHead(200, { "Content-Type": "text/xml; charset=utf-8" });
-  res.end('<?xml version="1.0" encoding="UTF-8"?><Response/>');
-}
-function twimlError(res, status, message) {
-  res.writeHead(status, { "Content-Type": "text/xml; charset=utf-8" });
-  res.end(
-    `<?xml version="1.0" encoding="UTF-8"?><Response><Message>${message}</Message></Response>`
-  );
-}
-var pendingMediaByConversation = /* @__PURE__ */ new Map();
-var dispatchQueueByConversation = /* @__PURE__ */ new Map();
 function resolvePendingMediaKey(accountId, fromPhone) {
   return `${accountId}:${fromPhone}`;
 }
+function uniqueMessageSids(sids) {
+  return [...new Set(sids.map((sid) => sid?.trim()).filter((sid) => Boolean(sid)))];
+}
+function combineBatchMessageText(items) {
+  return items.map((item) => item.messageText.trim()).filter(Boolean).join("\n\n");
+}
 async function downloadTwilioMedia(url, account) {
   try {
     const authHeader = "Basic " + Buffer.from(`${account.accountSid}:${account.authToken}`).toString("base64");
@@ -380,82 +471,88 @@ function enqueueConversationDispatch(key, task) {
     console.error(`[twilio-whatsapp] Conversation dispatch failed key=${key}:`, err);
   });
   dispatchQueueByConversation.set(key, next);
-  void next.finally(() => {
+  void next.then(() => {
     if (dispatchQueueByConversation.get(key) === next) {
       dispatchQueueByConversation.delete(key);
     }
   });
+  return next;
 }
 function stopBatchTimer(batch) {
-  if (batch.timer) {
-    clearTimeout(batch.timer);
-    batch.timer = void 0;
-  }
+  if (!batch.timer) return;
+  clearTimeout(batch.timer);
+  batch.timer = void 0;
 }
-function armBatchTimer(api, key, batch) {
+function armBatchTimer(api, dispatchInbound, key, batch) {
   stopBatchTimer(batch);
-  const flushMs = resolveMediaBatchFlushMs();
+  const batchAgeMs = Math.max(0, Date.now() - batch.firstReceivedAt);
+  const desiredWaitMs = batch.items.length === 1 ? resolveMediaBatchInitialWaitMs() : resolveMediaBatchFlushMs();
+  const remainingMaxWaitMs = Math.max(0, resolveMediaBatchMaxWaitMs() - batchAgeMs);
+  const waitMs = Math.min(desiredWaitMs, remainingMaxWaitMs);
   batch.timer = setTimeout(() => {
-    flushPendingMediaBatch(api, key, "timer");
-  }, flushMs);
-  const maybeTimer = batch.timer;
-  maybeTimer.unref?.();
-}
-function combineBatchMessageText(items) {
-  return items.map((item) => item.messageText.trim()).filter(Boolean).join("\n\n");
+    void flushPendingMediaBatch(api, dispatchInbound, key, "timer");
+  }, waitMs);
+  batch.timer.unref?.();
 }
-function uniqueMessageSids(sids) {
-  return [...new Set(sids.map((sid) => sid?.trim()).filter((sid) => Boolean(sid)))];
-}
-function flushPendingMediaBatch(api, key, reason) {
+async function flushPendingMediaBatch(api, dispatchInbound, key, reason) {
   const batch = pendingMediaByConversation.get(key);
   if (!batch) return;
   stopBatchTimer(batch);
   pendingMediaByConversation.delete(key);
   const items = [...batch.items].sort((a, b) => a.receivedAt - b.receivedAt);
-  const last = items[items.length - 1];
+  const last = items.at(-1);
   if (!last) return;
   const resolvedMedia = items.flatMap((item) => item.resolvedMedia);
-  if (!resolvedMedia.length && !combineBatchMessageText(items)) {
+  const messageText = combineBatchMessageText(items);
+  if (!resolvedMedia.length && !messageText) {
+    for (const item of items) item.resolve();
     return;
   }
   const messageSids = uniqueMessageSids(items.map((item) => item.fields.messageSid));
   console.log(
     `[twilio-whatsapp] Flushing media batch key=${key} reason=${reason} messages=${items.length} media=${resolvedMedia.length} sids=${messageSids.join(",") || "unknown"}`
   );
-  enqueueConversationDispatch(key, async () => {
-    await dispatchTwilioInbound(api, {
-      ...last,
-      messageText: combineBatchMessageText(items),
-      resolvedMedia,
-      messageSids
-    });
-  });
-}
-function queueMediaBatch(api, key, item) {
-  let batch = pendingMediaByConversation.get(key);
-  if (!batch) {
-    batch = { items: [] };
-    pendingMediaByConversation.set(key, batch);
-  }
-  batch.items.push(item);
-  console.log(
-    `[twilio-whatsapp] Buffered media inbound sid=${item.fields.messageSid || "unknown"} key=${key} pendingMessages=${batch.items.length} pendingMedia=${batch.items.reduce(
-      (count, pending) => count + pending.resolvedMedia.length,
-      0
-    )}`
-  );
-  if (batch.items.length >= resolveMediaBatchMaxItems()) {
-    flushPendingMediaBatch(api, key, "max-items");
-    return;
-  }
-  if (resolveMediaBatchFlushMs() === 0) {
-    flushPendingMediaBatch(api, key, "disabled");
-    return;
+  try {
+    await enqueueConversationDispatch(
+      key,
+      () => dispatchTwilioInbound(api, dispatchInbound, {
+        ...last,
+        messageText,
+        resolvedMedia,
+        messageSids
+      })
+    );
+    for (const item of items) item.resolve();
+  } catch (err) {
+    for (const item of items) item.reject(err);
   }
-  armBatchTimer(api, key, batch);
 }
-async function dispatchTwilioInbound(api, params) {
+function queueMediaBatch(api, dispatchInbound, key, item) {
+  return new Promise((resolve, reject) => {
+    let batch = pendingMediaByConversation.get(key);
+    if (!batch) {
+      batch = { items: [], firstReceivedAt: item.receivedAt };
+      pendingMediaByConversation.set(key, batch);
+    }
+    batch.items.push({ ...item, resolve, reject });
+    console.log(
+      `[twilio-whatsapp] Buffered media inbound sid=${item.fields.messageSid || "unknown"} key=${key} pendingMessages=${batch.items.length} pendingMedia=${batch.items.reduce(
+        (count, pending) => count + pending.resolvedMedia.length,
+        0
+      )}`
+    );
+    if (batch.items.length >= resolveMediaBatchMaxItems()) {
+      void flushPendingMediaBatch(api, dispatchInbound, key, "max-items");
+      return;
+    }
+    if (resolveMediaBatchFlushMs() === 0) {
+      void flushPendingMediaBatch(api, dispatchInbound, key, "disabled");
+      return;
+    }
+    armBatchTimer(api, dispatchInbound, key, batch);
+  });
+}
+async function dispatchTwilioInbound(api, dispatchInbound, params) {
   const {
     fields,
     stored,
@@ -472,25 +569,26 @@ async function dispatchTwilioInbound(api, params) {
     MediaPath: resolvedMedia[0].path,
     MediaUrl: resolvedMedia[0].path,
     MediaType: resolvedMedia[0].contentType,
-    MediaPaths: resolvedMedia.map((m) => m.path),
-    MediaUrls: resolvedMedia.map((m) => m.path),
-    MediaTypes: resolvedMedia.map((m) => m.contentType)
+    MediaPaths: resolvedMedia.map((media) => media.path),
+    MediaUrls: resolvedMedia.map((media) => media.path),
+    MediaTypes: resolvedMedia.map((media) => media.contentType)
   } : {};
   let bodyForAgent = messageText || void 0;
-  const firstAudio = resolvedMedia.find((m) => m.contentType.startsWith("audio/"));
+  const firstAudio = resolvedMedia.find((media) => media.contentType.startsWith("audio/"));
   if (firstAudio) {
     try {
       const cfgAny = stored.cfg;
       const agentId = cfgAny.bindings?.find(
-        (b) => b.match?.channel === "twilio-whatsapp" && b.match?.accountId === stored.accountId
+        (binding) => binding.match?.channel === "twilio-whatsapp" && binding.match?.accountId === stored.accountId
       )?.agentId;
-      const agentDir = cfgAny.agents?.list?.find(
-        (a) => a.id === agentId
-      )?.agentDir;
+      if (!agentId) {
+        throw new Error(`No agent binding found for WhatsApp account ${stored.accountId}`);
+      }
+      const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(stored.cfg, agentId);
       const auth = await api.runtime.modelAuth.resolveApiKeyForProvider({
         provider: "openai",
-        cfg: api.config,
-        agentDir
+        cfg: stored.cfg,
+        workspaceDir
       });
       if (!auth.apiKey) throw new Error("No OpenAI API key available for audio transcription");
       const audioBuffer = await readFile(firstAudio.path);
@@ -512,8 +610,7 @@ async function dispatchTwilioInbound(api, params) {
         const errBody = await transcribeRes.text();
         throw new Error(`OpenAI transcription HTTP ${transcribeRes.status}: ${errBody}`);
       }
-      const transcribeJson = await transcribeRes.json();
-      const text = transcribeJson.text;
+      const { text } = await transcribeRes.json();
       console.log("[twilio-whatsapp] Transcription result:", text);
       if (text) {
         bodyForAgent = messageText ? `${messageText}
@@ -560,10 +657,9 @@ ${text}` : text;
     }
   };
   try {
-    const timestamp = Date.now();
-    await dispatchInboundDirectDmWithRuntime({
+    await dispatchInbound({
       cfg: stored.cfg,
-      runtime: { channel: stored.channelRuntime },
+      runtime: api.runtime,
       channel: "twilio-whatsapp",
       channelLabel: "WhatsApp",
       accountId: account.accountId,
@@ -575,14 +671,16 @@ ${text}` : text;
       rawBody: messageText,
       bodyForAgent,
       messageId: fields.messageSid,
-      timestamp,
-      commandAuthorized: true,
+      timestamp: Date.now(),
+      commandAuthorized: params.commandAuthorized,
+      inboundAccessAuthorized: true,
       provider: "twilio-whatsapp",
       surface: "twilio-whatsapp",
       originatingChannel: "twilio-whatsapp",
       originatingTo: senderAddress,
       extraContext: mediaContext,
       deliver: async (payload) => {
+        stopTyping();
         const text = payload.text ?? "";
         const mediaUrl = payload.mediaUrl ?? payload.mediaUrls?.[0];
         console.log(
@@ -613,6 +711,7 @@ ${text}` : text;
         console.error("[twilio-whatsapp] Session record error:", err);
       },
       onDispatchError: (err, info) => {
+        stopTyping();
         console.error(`[twilio-whatsapp] Dispatch error (${info.kind}):`, err);
       }
     });
@@ -620,15 +719,33 @@ ${text}` : text;
     stopTyping();
   }
 }
-function registerTwilioWhatsappHttpRoutes(api) {
+function registerTwilioWhatsappHttpRoutes(api, dependencies = {}) {
+  const dispatchInbound = dependencies.dispatchInbound ?? dispatchInboundDirectDmWithRuntime;
+  const downloadMedia = dependencies.downloadMedia ?? downloadTwilioMedia;
   api.registerHttpRoute({
     path: "/twilio/whatsapp/events",
     auth: "plugin",
     handler: async (req, res) => {
-      const rawBody = await readBody(req);
-      const headers = req.headers;
-      const signature = String(headers["x-twilio-signature"] ?? "");
-      const webhookUrl = String(headers["x-twilio-webhook-url"] ?? "");
+      if (req.method !== "POST") {
+        twimlError(res, 405, "Method not allowed");
+        return true;
+      }
+      let rawBody;
+      try {
+        rawBody = await readRequestBodyWithLimit(req, {
+          maxBytes: WEBHOOK_MAX_BODY_BYTES,
+          timeoutMs: 1e4,
+          destroyOnLimit: false
+        });
+      } catch (err) {
+        if (isRequestBodyLimitError(err)) {
+          twimlError(res, err.statusCode, "Invalid request body");
+          return true;
+        }
+        throw err;
+      }
+      const signature = firstHeader(req, "x-twilio-signature");
+      const webhookUrl = firstHeader(req, "x-twilio-webhook-url");
       const fields = parseTwilioWebhook(rawBody);
       const toPhone = normalizePhoneNumber(fields.to);
       console.log(
@@ -646,20 +763,26 @@ function registerTwilioWhatsappHttpRoutes(api) {
         twimlError(res, 404, "Account not found");
         return true;
       }
-      if (webhookUrl && signature) {
-        const valid = verifyTwilioSignature({
-          authToken: account.authToken,
-          signature,
-          url: webhookUrl,
-          rawBody
-        });
-        if (!valid) {
-          console.error("[twilio-whatsapp] Invalid Twilio signature");
-          twimlError(res, 403, "Forbidden");
-          return true;
-        }
-      } else {
-        console.warn("[twilio-whatsapp] Skipping sig verification - headers missing");
+      if (!webhookUrl || !signature) {
+        console.error("[twilio-whatsapp] Missing forwarded Twilio signature headers");
+        twimlError(res, 403, "Forbidden");
+        return true;
+      }
+      const valid = verifyTwilioSignature({
+        authToken: account.authToken,
+        signature,
+        url: webhookUrl,
+        rawBody
+      });
+      if (!valid) {
+        console.error("[twilio-whatsapp] Invalid Twilio signature");
+        twimlError(res, 403, "Forbidden");
+        return true;
+      }
+      if (!fields.accountSid || fields.accountSid !== account.accountSid) {
+        console.error("[twilio-whatsapp] Twilio AccountSid does not match the target account");
+        twimlError(res, 403, "Forbidden");
+        return true;
       }
       const fromPhone = normalizePhoneNumber(fields.from);
       const senderAddress = `whatsapp:${fromPhone}`;
@@ -667,11 +790,33 @@ function registerTwilioWhatsappHttpRoutes(api) {
       const conversationLabel = fields.profileName || fromPhone;
       const messageText = fields.body.trim();
       const hasMedia = fields.media.length > 0;
-      const receivedAt = Date.now();
       if (!messageText && !hasMedia) {
         twimlOk(res);
         return true;
       }
+      const rateLimitKey = `${account.accountId}:${fromPhone}`;
+      if (webhookRateLimiter.isRateLimited(rateLimitKey)) {
+        console.warn(`[twilio-whatsapp] Inbound rate limit exceeded for account=${account.accountId}`);
+        twimlError(res, 429, "Too many requests");
+        return true;
+      }
+      const inboundAccess = resolveTwilioInboundAccess({
+        channelConfig: getTwilioChannelConfig(stored.cfg),
+        senderPhone: fromPhone
+      });
+      if (!inboundAccess.allowed) {
+        console.warn(
+          `[twilio-whatsapp] Blocked inbound sender for account=${account.accountId}: ${inboundAccess.reason}`
+        );
+        twimlOk(res);
+        return true;
+      }
+      if (fields.messageSid && replayCache.seen(`${account.accountId}:${fields.messageSid}`)) {
+        console.info(`[twilio-whatsapp] Ignoring replayed MessageSid for account=${account.accountId}`);
+        twimlOk(res);
+        return true;
+      }
+      const receivedAt = Date.now();
       twimlOk(res);
       console.log(
         `[twilio-whatsapp] Webhook acknowledged sid=${fields.messageSid || "unknown"} accountId=${account.accountId}`
@@ -679,7 +824,7 @@ function registerTwilioWhatsappHttpRoutes(api) {
       const resolvedMedia = [];
       if (hasMedia) {
         const results = await Promise.all(
-          fields.media.map((m) => downloadTwilioMedia(m.url, account))
+          fields.media.map((m) => downloadMedia(m.url, account))
         );
         for (const r of results) {
           if (r) resolvedMedia.push(r);
@@ -689,18 +834,22 @@ function registerTwilioWhatsappHttpRoutes(api) {
         );
       }
       const pendingMediaKey = resolvePendingMediaKey(account.accountId, fromPhone);
+      const dispatchParams = {
+        fields,
+        stored,
+        account,
+        toPhone,
+        fromPhone,
+        senderAddress,
+        recipientAddress,
+        conversationLabel,
+        messageText,
+        resolvedMedia,
+        commandAuthorized: inboundAccess.commandAuthorized
+      };
       if (hasMedia && resolvedMedia.length > 0) {
-        queueMediaBatch(api, pendingMediaKey, {
-          fields,
-          stored,
-          account,
-          toPhone,
-          fromPhone,
-          senderAddress,
-          recipientAddress,
-          conversationLabel,
-          messageText,
-          resolvedMedia,
+        await queueMediaBatch(api, dispatchInbound, pendingMediaKey, {
+          ...dispatchParams,
           receivedAt
         });
         return true;
@@ -712,22 +861,12 @@ function registerTwilioWhatsappHttpRoutes(api) {
         return true;
       }
       if (!hasMedia) {
-        flushPendingMediaBatch(api, pendingMediaKey, "before-text");
+        await flushPendingMediaBatch(api, dispatchInbound, pendingMediaKey, "before-text");
       }
-      enqueueConversationDispatch(pendingMediaKey, async () => {
-        await dispatchTwilioInbound(api, {
-          fields,
-          stored,
-          account,
-          toPhone,
-          fromPhone,
-          senderAddress,
-          recipientAddress,
-          conversationLabel,
-          messageText,
-          resolvedMedia
-        });
-      });
+      await enqueueConversationDispatch(
+        pendingMediaKey,
+        () => dispatchTwilioInbound(api, dispatchInbound, dispatchParams)
+      );
       return true;
     }
   });

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "twilio-whatsapp",
   "name": "Twilio WhatsApp",
   "description": "WhatsApp channel via Twilio Business API (ISV/WABA)",
-  "version": "1.0.0",
+  "version": "1.1.27",
   "channels": ["twilio-whatsapp"],
   "channelConfigs": {
     "twilio-whatsapp": {

package/package.json

@@ -1,36 +1,51 @@
-{
-  "name": "@daolmedo/openclaw-twilio-whatsapp",
-  "version": "1.1.25",
-  "description": "Twilio WhatsApp channel plugin for OpenClaw (Cody ISV)",
-  "type": "module",
-  "exports": {
-    ".": "./dist/index.js"
-  },
-  "files": [
-    "dist",
-    "openclaw.plugin.json"
-  ],
-  "scripts": {
-    "build": "esbuild index.ts --bundle --platform=node --format=esm --external:openclaw --external:openclaw/* --external:twilio --outfile=dist/index.js",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "twilio": "^5.4.0"
-  },
-  "devDependencies": {
-    "esbuild": "^0.28.0",
-    "typescript": "^5.4.0"
-  },
-  "openclaw": {
-    "extensions": [
-      "./dist/index.js"
-    ],
-    "channel": {
-      "id": "twilio-whatsapp",
-      "label": "Twilio WhatsApp"
-    },
-    "install": {
-      "minHostVersion": ">=2026.3.24"
-    }
-  }
-}
+{
+  "name": "@daolmedo/openclaw-twilio-whatsapp",
+  "version": "1.1.27",
+  "description": "Twilio WhatsApp channel plugin for OpenClaw (Cody ISV)",
+  "type": "module",
+  "engines": {
+    "node": ">=24.16.0 <25 || >=26.1.0"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json"
+  ],
+  "scripts": {
+    "build": "esbuild index.ts --bundle --platform=node --format=esm --external:openclaw --external:openclaw/* --external:twilio --outfile=dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "esbuild test/*.test.ts --bundle --platform=node --format=esm --external:openclaw --external:openclaw/* --external:twilio --outdir=.test-dist --out-extension:.js=.mjs --log-level=warning && node --test .test-dist/*.test.mjs",
+    "check": "npm run typecheck && npm test && npm run build",
+    "prepublishOnly": "npm run check"
+  },
+  "dependencies": {
+    "twilio": "^5.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.4",
+    "esbuild": "^0.28.0",
+    "openclaw": "2026.9.4",
+    "typescript": "^5.4.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "channel": {
+      "id": "twilio-whatsapp",
+      "label": "Twilio WhatsApp"
+    },
+    "install": {
+      "minHostVersion": ">=2026.9.4"
+    },
+    "compat": {
+      "pluginApi": ">=2026.9.4"
+    },
+    "build": {
+      "openclawVersion": "2026.9.4",
+      "pluginSdkVersion": "2026.9.4"
+    }
+  }
+}

package/dist/index.d.ts

@@ -1,10 +0,0 @@
-declare const _default: {
-    id: string;
-    name: string;
-    description: string;
-    configSchema: import("openclaw/channels/plugins/types.plugin.js").ChannelConfigSchema;
-    register: (api: import("openclaw/plugins/types.js").OpenClawPluginApi) => void;
-    channelPlugin: import("openclaw/plugin-sdk/channel-core.js").ChannelPlugin<import("./src/accounts.js").ResolvedTwilioAccount>;
-    setChannelRuntime?: (runtime: import("openclaw/plugin-sdk/channel-core.js").PluginRuntime) => void;
-};
-export default _default;

package/dist/src/accounts.d.ts

@@ -1,11 +0,0 @@
-import type { OpenClawConfig } from "openclaw/channels/plugins/types.js";
-export type ResolvedTwilioAccount = {
-    accountId: string;
-    accountSid: string;
-    authToken: string;
-    phoneNumber: string;
-};
-export declare function listTwilioAccountIds(cfg: OpenClawConfig): string[];
-export declare function resolveTwilioAccount(cfg: OpenClawConfig, accountId?: string | null): ResolvedTwilioAccount;
-export declare function findTwilioAccountByPhoneNumber(cfg: OpenClawConfig, phoneNumber: string): ResolvedTwilioAccount | undefined;
-export declare function normalizePhoneNumber(phone: string): string;

package/dist/src/accounts.js

@@ -1,38 +0,0 @@
-const getChannelConfig = (cfg) => cfg.channels &&
-    cfg.channels["twilio-whatsapp"]
-    ? cfg.channels["twilio-whatsapp"]
-    : undefined;
-export function listTwilioAccountIds(cfg) {
-    const ch = getChannelConfig(cfg);
-    return Object.keys(ch?.accounts ?? {});
-}
-export function resolveTwilioAccount(cfg, accountId) {
-    const ch = getChannelConfig(cfg);
-    const id = accountId ?? "default";
-    const entry = ch?.accounts?.[id];
-    if (!entry) {
-        throw new Error(`[twilio-whatsapp] No account configured for accountId="${id}". ` +
-            `Add channels.twilio-whatsapp.accounts.${id} to openclaw.json.`);
-    }
-    return {
-        accountId: id,
-        accountSid: entry.accountSid,
-        authToken: entry.authToken,
-        phoneNumber: entry.phoneNumber,
-    };
-}
-export function findTwilioAccountByPhoneNumber(cfg, phoneNumber) {
-    const ch = getChannelConfig(cfg);
-    if (!ch?.accounts)
-        return undefined;
-    for (const [id, entry] of Object.entries(ch.accounts)) {
-        const normalized = normalizePhoneNumber(entry.phoneNumber);
-        if (normalized === normalizePhoneNumber(phoneNumber)) {
-            return { accountId: id, ...entry };
-        }
-    }
-    return undefined;
-}
-export function normalizePhoneNumber(phone) {
-    return phone.replace(/^whatsapp:/, "").replace(/\s+/g, "");
-}

package/dist/src/channel.d.ts

@@ -1,3 +0,0 @@
-import type { ChannelPlugin } from "openclaw/channels/plugins/types.js";
-import { type ResolvedTwilioAccount } from "./accounts.js";
-export declare const twilioWhatsappPlugin: ChannelPlugin<ResolvedTwilioAccount>;

package/dist/src/channel.js

@@ -1,76 +0,0 @@
-import { listTwilioAccountIds, normalizePhoneNumber, resolveTwilioAccount, } from "./accounts.js";
-import { twilioWhatsappOutbound } from "./outbound-adapter.js";
-import { clearRuntimeForPhoneNumber, setRuntimeForPhoneNumber } from "./runtime-store.js";
-export const twilioWhatsappPlugin = {
-    id: "twilio-whatsapp",
-    meta: {
-        id: "twilio-whatsapp",
-        label: "Twilio WhatsApp",
-        selectionLabel: "WhatsApp (Twilio)",
-        docsPath: "/channels/twilio-whatsapp",
-        blurb: "WhatsApp messaging via Twilio Business API",
-        markdownCapable: false,
-        showInSetup: true,
-        showConfigured: true,
-    },
-    capabilities: {
-        chatTypes: ["direct"],
-        media: true,
-    },
-    config: {
-        listAccountIds: listTwilioAccountIds,
-        resolveAccount(cfg, accountId) {
-            return resolveTwilioAccount(cfg, accountId);
-        },
-        isConfigured(account) {
-            return Boolean(account.accountSid && account.authToken && account.phoneNumber);
-        },
-        describeAccount(account) {
-            return {
-                accountId: account.accountId,
-                configured: Boolean(account.accountSid && account.authToken && account.phoneNumber),
-                name: `WhatsApp ${account.phoneNumber}`,
-            };
-        },
-        hasConfiguredState({ cfg }) {
-            return listTwilioAccountIds(cfg).length > 0;
-        },
-    },
-    outbound: twilioWhatsappOutbound,
-    gateway: {
-        async startAccount(ctx) {
-            const account = ctx.account;
-            const phoneNumber = normalizePhoneNumber(account.phoneNumber);
-            if (!ctx.channelRuntime) {
-                console.error(`[twilio-whatsapp] channelRuntime not provided for account ${ctx.accountId}. ` +
-                    "Inbound dispatch will not work.");
-                return;
-            }
-            setRuntimeForPhoneNumber(phoneNumber, {
-                cfg: ctx.cfg,
-                accountId: ctx.accountId,
-                channelRuntime: ctx.channelRuntime,
-            });
-            ctx.setStatus({
-                accountId: ctx.accountId,
-                running: true,
-                connected: true,
-                configured: true,
-                name: `WhatsApp ${account.phoneNumber}`,
-                webhookPath: "/twilio/whatsapp/events",
-            });
-            console.log(`[twilio-whatsapp] Account ${ctx.accountId} started, listening on /twilio/whatsapp/events for ${account.phoneNumber}`);
-            await new Promise((_, reject) => {
-                ctx.abortSignal.addEventListener("abort", () => reject(new Error("aborted")));
-            }).catch(() => {
-                clearRuntimeForPhoneNumber(phoneNumber);
-                ctx.setStatus({
-                    accountId: ctx.accountId,
-                    running: false,
-                    connected: false,
-                });
-                console.log(`[twilio-whatsapp] Account ${ctx.accountId} stopped`);
-            });
-        },
-    },
-};

package/dist/src/http-routes.d.ts

@@ -1,2 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugins/types.js";
-export declare function registerTwilioWhatsappHttpRoutes(api: OpenClawPluginApi): void;

package/dist/src/http-routes.js

@@ -1,117 +0,0 @@
-import { dispatchInboundDirectDmWithRuntime } from "openclaw/plugin-sdk/direct-dm.js";
-import { findTwilioAccountByPhoneNumber, normalizePhoneNumber, } from "./accounts.js";
-import { parseTwilioWebhook, verifyTwilioSignature } from "./webhook.js";
-import { sendTwilioWhatsappMessage } from "./send.js";
-import { getRuntimeForPhoneNumber } from "./runtime-store.js";
-async function readBody(req) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        req.on("data", (chunk) => chunks.push(chunk));
-        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
-        req.on("error", reject);
-    });
-}
-function twimlOk(res) {
-    res.writeHead(200, { "Content-Type": "text/xml; charset=utf-8" });
-    res.end('<?xml version="1.0" encoding="UTF-8"?><Response/>');
-}
-function twimlError(res, status, message) {
-    res.writeHead(status, { "Content-Type": "text/xml; charset=utf-8" });
-    res.end(`<?xml version="1.0" encoding="UTF-8"?><Response><Message>${message}</Message></Response>`);
-}
-export function registerTwilioWhatsappHttpRoutes(api) {
-    api.registerHttpRoute({
-        path: "/twilio/whatsapp/events",
-        auth: "plugin",
-        handler: async (req, res) => {
-            const rawBody = await readBody(req);
-            const headers = req.headers;
-            const signature = String(headers["x-twilio-signature"] ?? "");
-            const webhookUrl = String(headers["x-twilio-webhook-url"] ?? "");
-            const fields = parseTwilioWebhook(rawBody);
-            const toPhone = normalizePhoneNumber(fields.to);
-            const stored = getRuntimeForPhoneNumber(toPhone);
-            if (!stored) {
-                console.error(`[twilio-whatsapp] No runtime found for To=${fields.to}`);
-                twimlError(res, 404, "No agent bound to this number");
-                return true;
-            }
-            const account = findTwilioAccountByPhoneNumber(stored.cfg, toPhone);
-            if (!account) {
-                console.error(`[twilio-whatsapp] Account not found for phone=${toPhone}`);
-                twimlError(res, 404, "Account not found");
-                return true;
-            }
-            if (webhookUrl && signature) {
-                const valid = verifyTwilioSignature({
-                    authToken: account.authToken,
-                    signature,
-                    url: webhookUrl,
-                    rawBody,
-                });
-                if (!valid) {
-                    console.error("[twilio-whatsapp] Invalid Twilio signature");
-                    twimlError(res, 403, "Forbidden");
-                    return true;
-                }
-            }
-            else {
-                console.warn("[twilio-whatsapp] Skipping sig verification — headers missing");
-            }
-            const fromPhone = normalizePhoneNumber(fields.from);
-            const senderAddress = `whatsapp:${fromPhone}`;
-            const recipientAddress = `whatsapp:${toPhone}`;
-            const conversationLabel = fields.profileName || fromPhone;
-            const messageText = fields.body.trim();
-            const hasMedia = fields.media.length > 0;
-            if (!messageText && !hasMedia) {
-                twimlOk(res);
-                return true;
-            }
-            const bodyForAgent = hasMedia
-                ? [messageText, ...fields.media.map((m) => `[Media: ${m.url}]`)].filter(Boolean).join("\n")
-                : messageText;
-            twimlOk(res);
-            dispatchInboundDirectDmWithRuntime({
-                cfg: stored.cfg,
-                runtime: { channel: stored.channelRuntime },
-                channel: "twilio-whatsapp",
-                channelLabel: "WhatsApp",
-                accountId: account.accountId,
-                peer: { kind: "direct", id: fromPhone },
-                senderId: fromPhone,
-                senderAddress,
-                recipientAddress,
-                conversationLabel,
-                rawBody: messageText,
-                bodyForAgent,
-                messageId: fields.messageSid,
-                timestamp: Date.now(),
-                commandAuthorized: true,
-                deliver: async (payload) => {
-                    const text = payload.text ?? "";
-                    const mediaUrl = payload.mediaUrl ?? payload.mediaUrls?.[0];
-                    if (!text && !mediaUrl)
-                        return;
-                    await sendTwilioWhatsappMessage({
-                        accountSid: account.accountSid,
-                        authToken: account.authToken,
-                        from: toPhone,
-                        to: fromPhone,
-                        body: text || undefined,
-                        mediaUrl,
-                    });
-                },
-                onRecordError: (err) => {
-                    console.error("[twilio-whatsapp] Session record error:", err);
-                },
-                onDispatchError: (err, info) => {
-                    console.error(`[twilio-whatsapp] Dispatch error (${info.kind}):`, err);
-                },
-            }).catch((err) => {
-                console.error("[twilio-whatsapp] Unhandled dispatch error:", err);
-            });
-            return true;
-        },
-    });
-}

package/dist/src/outbound-adapter.d.ts

@@ -1,2 +0,0 @@
-import type { ChannelOutboundAdapter } from "openclaw/channels/plugins/types.adapters.js";
-export declare const twilioWhatsappOutbound: ChannelOutboundAdapter;

package/dist/src/outbound-adapter.js

@@ -1,31 +0,0 @@
-import { resolveTwilioAccount } from "./accounts.js";
-import { sendTwilioWhatsappMessage } from "./send.js";
-async function deliver(ctx) {
-    const account = resolveTwilioAccount(ctx.cfg, ctx.accountId);
-    const sid = await sendTwilioWhatsappMessage({
-        accountSid: account.accountSid,
-        authToken: account.authToken,
-        from: account.phoneNumber,
-        to: ctx.to,
-        body: ctx.text || undefined,
-        mediaUrl: ctx.mediaUrl,
-    });
-    return sid;
-}
-export const twilioWhatsappOutbound = {
-    deliveryMode: "direct",
-    async sendText(ctx) {
-        const messageId = await deliver(ctx);
-        return {
-            channel: "twilio-whatsapp",
-            messageId,
-        };
-    },
-    async sendMedia(ctx) {
-        const messageId = await deliver(ctx);
-        return {
-            channel: "twilio-whatsapp",
-            messageId,
-        };
-    },
-};

package/dist/src/runtime-store.d.ts

@@ -1,9 +0,0 @@
-import type { OpenClawConfig } from "openclaw/channels/plugins/types.js";
-export type StoredTwilioRuntime = {
-    cfg: OpenClawConfig;
-    accountId: string;
-    channelRuntime: NonNullable<import("openclaw/channels/plugins/types.adapters.js").ChannelGatewayContext["channelRuntime"]>;
-};
-export declare function setRuntimeForPhoneNumber(phoneNumber: string, runtime: StoredTwilioRuntime): void;
-export declare function clearRuntimeForPhoneNumber(phoneNumber: string): void;
-export declare function getRuntimeForPhoneNumber(phoneNumber: string): StoredTwilioRuntime | undefined;

package/dist/src/runtime-store.js

@@ -1,10 +0,0 @@
-const phoneToRuntime = new Map();
-export function setRuntimeForPhoneNumber(phoneNumber, runtime) {
-    phoneToRuntime.set(phoneNumber, runtime);
-}
-export function clearRuntimeForPhoneNumber(phoneNumber) {
-    phoneToRuntime.delete(phoneNumber);
-}
-export function getRuntimeForPhoneNumber(phoneNumber) {
-    return phoneToRuntime.get(phoneNumber);
-}

package/dist/src/send.d.ts

@@ -1,8 +0,0 @@
-export declare function sendTwilioWhatsappMessage(opts: {
-    accountSid: string;
-    authToken: string;
-    from: string;
-    to: string;
-    body?: string;
-    mediaUrl?: string;
-}): Promise<string>;

package/dist/src/send.js

@@ -1,13 +0,0 @@
-import twilio from "twilio";
-export async function sendTwilioWhatsappMessage(opts) {
-    const client = twilio(opts.accountSid, opts.authToken);
-    const from = opts.from.startsWith("whatsapp:") ? opts.from : `whatsapp:${opts.from}`;
-    const to = opts.to.startsWith("whatsapp:") ? opts.to : `whatsapp:${opts.to}`;
-    const msg = await client.messages.create({
-        from,
-        to,
-        ...(opts.body ? { body: opts.body } : {}),
-        ...(opts.mediaUrl ? { mediaUrl: [opts.mediaUrl] } : {}),
-    });
-    return msg.sid;
-}

package/dist/src/webhook.d.ts

@@ -1,20 +0,0 @@
-export type ParsedTwilioWebhook = {
-    from: string;
-    to: string;
-    body: string;
-    waId: string;
-    profileName: string;
-    messageSid: string;
-    media: Array<{
-        url: string;
-        contentType: string;
-    }>;
-    repliedToSid?: string;
-};
-export declare function verifyTwilioSignature(params: {
-    authToken: string;
-    signature: string;
-    url: string;
-    rawBody: string;
-}): boolean;
-export declare function parseTwilioWebhook(rawBody: string): ParsedTwilioWebhook;

package/dist/src/webhook.js

@@ -1,28 +0,0 @@
-import twilio from "twilio";
-export function verifyTwilioSignature(params) {
-    try {
-        const parsed = Object.fromEntries(new URLSearchParams(params.rawBody));
-        return twilio.validateRequest(params.authToken, params.signature, params.url, parsed);
-    }
-    catch {
-        return false;
-    }
-}
-export function parseTwilioWebhook(rawBody) {
-    const p = Object.fromEntries(new URLSearchParams(rawBody));
-    const numMedia = parseInt(p["NumMedia"] ?? "0", 10);
-    const media = Array.from({ length: numMedia }, (_, i) => ({
-        url: p[`MediaUrl${i}`] ?? "",
-        contentType: p[`MediaContentType${i}`] ?? "application/octet-stream",
-    }));
-    return {
-        from: (p["From"] ?? "").replace("whatsapp:", ""),
-        to: (p["To"] ?? "").replace("whatsapp:", ""),
-        body: p["Body"] ?? "",
-        waId: p["WaId"] ?? "",
-        profileName: p["ProfileName"] ?? "",
-        messageSid: p["MessageSid"] ?? "",
-        media,
-        repliedToSid: p["OriginalRepliedMessageSid"],
-    };
-}