@openclaw/zalo 2026.2.25 → 2026.3.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2026.3.2
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.1
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.26
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.2.25
 
 ### Changes

package/index.ts

@@ -1,7 +1,6 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { zaloDock, zaloPlugin } from "./src/channel.js";
-import { handleZaloWebhookRequest } from "./src/monitor.js";
 import { setZaloRuntime } from "./src/runtime.js";
 
 const plugin = {
@@ -12,7 +11,6 @@ const plugin = {
   register(api: OpenClawPluginApi) {
     setZaloRuntime(api.runtime);
     api.registerChannel({ plugin: zaloPlugin, dock: zaloDock });
-    api.registerHttpHandler(handleZaloWebhookRequest);
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/zalo",
-  "version": "2026.2.25",
+  "version": "2026.3.2",
   "description": "OpenClaw Zalo channel plugin",
   "type": "module",
   "dependencies": {

package/src/accounts.ts

@@ -1,5 +1,9 @@
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  normalizeOptionalAccountId,
+} from "openclaw/plugin-sdk/account-id";
 import { resolveZaloToken } from "./token.js";
 import type { ResolvedZaloAccount, ZaloAccountConfig, ZaloConfig } from "./types.js";
 
@@ -23,8 +27,12 @@ export function listZaloAccountIds(cfg: OpenClawConfig): string[] {
 
 export function resolveDefaultZaloAccountId(cfg: OpenClawConfig): string {
   const zaloConfig = cfg.channels?.zalo as ZaloConfig | undefined;
-  if (zaloConfig?.defaultAccount?.trim()) {
-    return zaloConfig.defaultAccount.trim();
+  const preferred = normalizeOptionalAccountId(zaloConfig?.defaultAccount);
+  if (
+    preferred &&
+    listZaloAccountIds(cfg).some((accountId) => normalizeAccountId(accountId) === preferred)
+  ) {
+    return preferred;
   }
   const ids = listZaloAccountIds(cfg);
   if (ids.includes(DEFAULT_ACCOUNT_ID)) {
@@ -54,6 +62,7 @@ function mergeZaloAccountConfig(cfg: OpenClawConfig, accountId: string): ZaloAcc
 export function resolveZaloAccount(params: {
   cfg: OpenClawConfig;
   accountId?: string | null;
+  allowUnresolvedSecretRef?: boolean;
 }): ResolvedZaloAccount {
   const accountId = normalizeAccountId(params.accountId);
   const baseEnabled = (params.cfg.channels?.zalo as ZaloConfig | undefined)?.enabled !== false;
@@ -63,6 +72,7 @@ export function resolveZaloAccount(params: {
   const tokenResolution = resolveZaloToken(
     params.cfg.channels?.zalo as ZaloConfig | undefined,
     accountId,
+    { allowUnresolvedSecretRef: params.allowUnresolvedSecretRef },
   );
 
   return {

package/src/channel.sendpayload.test.ts

@@ -0,0 +1,102 @@
+import type { ReplyPayload } from "openclaw/plugin-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { zaloPlugin } from "./channel.js";
+
+vi.mock("./send.js", () => ({
+  sendMessageZalo: vi.fn().mockResolvedValue({ ok: true, messageId: "zl-1" }),
+}));
+
+function baseCtx(payload: ReplyPayload) {
+  return {
+    cfg: {},
+    to: "123456789",
+    text: "",
+    payload,
+  };
+}
+
+describe("zaloPlugin outbound sendPayload", () => {
+  let mockedSend: ReturnType<typeof vi.mocked<(typeof import("./send.js"))["sendMessageZalo"]>>;
+
+  beforeEach(async () => {
+    const mod = await import("./send.js");
+    mockedSend = vi.mocked(mod.sendMessageZalo);
+    mockedSend.mockClear();
+    mockedSend.mockResolvedValue({ ok: true, messageId: "zl-1" });
+  });
+
+  it("text-only delegates to sendText", async () => {
+    mockedSend.mockResolvedValue({ ok: true, messageId: "zl-t1" });
+
+    const result = await zaloPlugin.outbound!.sendPayload!(baseCtx({ text: "hello" }));
+
+    expect(mockedSend).toHaveBeenCalledWith("123456789", "hello", expect.any(Object));
+    expect(result).toMatchObject({ channel: "zalo", messageId: "zl-t1" });
+  });
+
+  it("single media delegates to sendMedia", async () => {
+    mockedSend.mockResolvedValue({ ok: true, messageId: "zl-m1" });
+
+    const result = await zaloPlugin.outbound!.sendPayload!(
+      baseCtx({ text: "cap", mediaUrl: "https://example.com/a.jpg" }),
+    );
+
+    expect(mockedSend).toHaveBeenCalledWith(
+      "123456789",
+      "cap",
+      expect.objectContaining({ mediaUrl: "https://example.com/a.jpg" }),
+    );
+    expect(result).toMatchObject({ channel: "zalo" });
+  });
+
+  it("multi-media iterates URLs with caption on first", async () => {
+    mockedSend
+      .mockResolvedValueOnce({ ok: true, messageId: "zl-1" })
+      .mockResolvedValueOnce({ ok: true, messageId: "zl-2" });
+
+    const result = await zaloPlugin.outbound!.sendPayload!(
+      baseCtx({
+        text: "caption",
+        mediaUrls: ["https://example.com/1.jpg", "https://example.com/2.jpg"],
+      }),
+    );
+
+    expect(mockedSend).toHaveBeenCalledTimes(2);
+    expect(mockedSend).toHaveBeenNthCalledWith(
+      1,
+      "123456789",
+      "caption",
+      expect.objectContaining({ mediaUrl: "https://example.com/1.jpg" }),
+    );
+    expect(mockedSend).toHaveBeenNthCalledWith(
+      2,
+      "123456789",
+      "",
+      expect.objectContaining({ mediaUrl: "https://example.com/2.jpg" }),
+    );
+    expect(result).toMatchObject({ channel: "zalo", messageId: "zl-2" });
+  });
+
+  it("empty payload returns no-op", async () => {
+    const result = await zaloPlugin.outbound!.sendPayload!(baseCtx({}));
+
+    expect(mockedSend).not.toHaveBeenCalled();
+    expect(result).toEqual({ channel: "zalo", messageId: "" });
+  });
+
+  it("chunking splits long text", async () => {
+    mockedSend
+      .mockResolvedValueOnce({ ok: true, messageId: "zl-c1" })
+      .mockResolvedValueOnce({ ok: true, messageId: "zl-c2" });
+
+    const longText = "a".repeat(3000);
+    const result = await zaloPlugin.outbound!.sendPayload!(baseCtx({ text: longText }));
+
+    // textChunkLimit is 2000 with chunkTextForOutbound, so it should split
+    expect(mockedSend.mock.calls.length).toBeGreaterThanOrEqual(2);
+    for (const call of mockedSend.mock.calls) {
+      expect((call[1] as string).length).toBeLessThanOrEqual(2000);
+    }
+    expect(result).toMatchObject({ channel: "zalo" });
+  });
+});

package/src/channel.ts

@@ -32,6 +32,7 @@ import { ZaloConfigSchema } from "./config-schema.js";
 import { zaloOnboardingAdapter } from "./onboarding.js";
 import { probeZalo } from "./probe.js";
 import { resolveZaloProxyFetch } from "./proxy.js";
+import { normalizeSecretInputString } from "./secret-input.js";
 import { sendMessageZalo } from "./send.js";
 import { collectZaloStatusIssues } from "./status-issues.js";
 
@@ -302,6 +303,40 @@ export const zaloPlugin: ChannelPlugin<ResolvedZaloAccount> = {
     chunker: chunkTextForOutbound,
     chunkerMode: "text",
     textChunkLimit: 2000,
+    sendPayload: async (ctx) => {
+      const text = ctx.payload.text ?? "";
+      const urls = ctx.payload.mediaUrls?.length
+        ? ctx.payload.mediaUrls
+        : ctx.payload.mediaUrl
+          ? [ctx.payload.mediaUrl]
+          : [];
+      if (!text && urls.length === 0) {
+        return { channel: "zalo", messageId: "" };
+      }
+      if (urls.length > 0) {
+        let lastResult = await zaloPlugin.outbound!.sendMedia!({
+          ...ctx,
+          text,
+          mediaUrl: urls[0],
+        });
+        for (let i = 1; i < urls.length; i++) {
+          lastResult = await zaloPlugin.outbound!.sendMedia!({
+            ...ctx,
+            text: "",
+            mediaUrl: urls[i],
+          });
+        }
+        return lastResult;
+      }
+      const outbound = zaloPlugin.outbound!;
+      const limit = outbound.textChunkLimit;
+      const chunks = limit && outbound.chunker ? outbound.chunker(text, limit) : [text];
+      let lastResult: Awaited<ReturnType<NonNullable<typeof outbound.sendText>>>;
+      for (const chunk of chunks) {
+        lastResult = await outbound.sendText!({ ...ctx, text: chunk });
+      }
+      return lastResult!;
+    },
     sendText: async ({ to, text, accountId, cfg }) => {
       const result = await sendMessageZalo(to, text, {
         accountId: accountId ?? undefined,
@@ -388,7 +423,7 @@ export const zaloPlugin: ChannelPlugin<ResolvedZaloAccount> = {
         abortSignal: ctx.abortSignal,
         useWebhook: Boolean(account.config.webhookUrl),
         webhookUrl: account.config.webhookUrl,
-        webhookSecret: account.config.webhookSecret,
+        webhookSecret: normalizeSecretInputString(account.config.webhookSecret),
         webhookPath: account.config.webhookPath,
         fetcher,
         statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),

package/src/config-schema.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { ZaloConfigSchema } from "./config-schema.js";
+
+describe("ZaloConfigSchema SecretInput", () => {
+  it("accepts SecretRef botToken and webhookSecret at top-level", () => {
+    const result = ZaloConfigSchema.safeParse({
+      botToken: { source: "env", provider: "default", id: "ZALO_BOT_TOKEN" },
+      webhookUrl: "https://example.com/zalo",
+      webhookSecret: { source: "env", provider: "default", id: "ZALO_WEBHOOK_SECRET" },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts SecretRef botToken and webhookSecret on account", () => {
+    const result = ZaloConfigSchema.safeParse({
+      accounts: {
+        work: {
+          botToken: { source: "env", provider: "default", id: "ZALO_WORK_BOT_TOKEN" },
+          webhookUrl: "https://example.com/zalo/work",
+          webhookSecret: {
+            source: "env",
+            provider: "default",
+            id: "ZALO_WORK_WEBHOOK_SECRET",
+          },
+        },
+      },
+    });
+    expect(result.success).toBe(true);
+  });
+});

package/src/config-schema.ts

@@ -1,5 +1,6 @@
 import { MarkdownConfigSchema } from "openclaw/plugin-sdk";
 import { z } from "zod";
+import { buildSecretInputSchema } from "./secret-input.js";
 
 const allowFromEntry = z.union([z.string(), z.number()]);
 
@@ -7,10 +8,10 @@ const zaloAccountSchema = z.object({
   name: z.string().optional(),
   enabled: z.boolean().optional(),
   markdown: MarkdownConfigSchema,
-  botToken: z.string().optional(),
+  botToken: buildSecretInputSchema().optional(),
   tokenFile: z.string().optional(),
   webhookUrl: z.string().optional(),
-  webhookSecret: z.string().optional(),
+  webhookSecret: buildSecretInputSchema().optional(),
   webhookPath: z.string().optional(),
   dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
   allowFrom: z.array(allowFromEntry).optional(),

package/src/monitor.ts

@@ -1,10 +1,13 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { MarkdownTableMode, OpenClawConfig, OutboundReplyPayload } from "openclaw/plugin-sdk";
 import {
+  createScopedPairingAccess,
   createReplyPrefixOptions,
-  resolveSenderCommandAuthorization,
+  resolveDirectDmAuthorizationOutcome,
+  resolveSenderCommandAuthorizationWithRuntime,
   resolveOutboundMediaUrls,
   resolveDefaultGroupPolicy,
+  resolveInboundRouteEnvelopeBuilderWithRuntime,
   sendMediaWithLeadingCaption,
   resolveWebhookPath,
   warnMissingProviderGroupPolicyFallbackOnce,
@@ -27,6 +30,9 @@ import {
   resolveZaloRuntimeGroupPolicy,
 } from "./group-access.js";
 import {
+  clearZaloWebhookSecurityStateForTest,
+  getZaloWebhookRateLimitStateSizeForTest,
+  getZaloWebhookStatusCounterSizeForTest,
   handleZaloWebhookRequest as handleZaloWebhookRequestInternal,
   registerZaloWebhookTarget as registerZaloWebhookTargetInternal,
   type ZaloWebhookTarget,
@@ -69,9 +75,32 @@ function logVerbose(core: ZaloCoreRuntime, runtime: ZaloRuntimeEnv, message: str
 }
 
 export function registerZaloWebhookTarget(target: ZaloWebhookTarget): () => void {
-  return registerZaloWebhookTargetInternal(target);
+  return registerZaloWebhookTargetInternal(target, {
+    route: {
+      auth: "plugin",
+      match: "exact",
+      pluginId: "zalo",
+      source: "zalo-webhook",
+      accountId: target.account.accountId,
+      log: target.runtime.log,
+      handler: async (req, res) => {
+        const handled = await handleZaloWebhookRequest(req, res);
+        if (!handled && !res.headersSent) {
+          res.statusCode = 404;
+          res.setHeader("Content-Type", "text/plain; charset=utf-8");
+          res.end("Not Found");
+        }
+      },
+    },
+  });
 }
 
+export {
+  clearZaloWebhookSecurityStateForTest,
+  getZaloWebhookRateLimitStateSizeForTest,
+  getZaloWebhookStatusCounterSizeForTest,
+};
+
 export async function handleZaloWebhookRequest(
   req: IncomingMessage,
   res: ServerResponse,
@@ -142,7 +171,7 @@ function startPollingLoop(params: {
       if (err instanceof ZaloApiError && err.isPollingTimeout) {
         // no updates
       } else if (!isStopped() && !abortSignal.aborted) {
-        console.error(`[${account.accountId}] Zalo polling error:`, err);
+        runtime.error?.(`[${account.accountId}] Zalo polling error: ${String(err)}`);
         await new Promise((resolve) => setTimeout(resolve, 5000));
       }
     }
@@ -189,10 +218,12 @@ async function processUpdate(
       );
       break;
     case "message.sticker.received":
-      console.log(`[${account.accountId}] Received sticker from ${message.from.id}`);
+      logVerbose(core, runtime, `[${account.accountId}] Received sticker from ${message.from.id}`);
       break;
     case "message.unsupported.received":
-      console.log(
+      logVerbose(
+        core,
+        runtime,
         `[${account.accountId}] Received unsupported message type from ${message.from.id}`,
       );
       break;
@@ -258,7 +289,7 @@ async function handleImageMessage(
       mediaPath = saved.path;
       mediaType = saved.contentType;
     } catch (err) {
-      console.error(`[${account.accountId}] Failed to download Zalo image:`, err);
+      runtime.error?.(`[${account.accountId}] Failed to download Zalo image: ${String(err)}`);
     }
   }
 
@@ -303,6 +334,11 @@ async function processMessageWithPipeline(params: {
     statusSink,
     fetcher,
   } = params;
+  const pairing = createScopedPairingAccess({
+    core,
+    channel: "zalo",
+    accountId: account.accountId,
+  });
   const { from, chat, message_id, date } = message;
 
   const isGroup = chat.chat_type === "GROUP";
@@ -349,82 +385,76 @@ async function processMessageWithPipeline(params: {
   }
 
   const rawBody = text?.trim() || (mediaPath ? "<media:image>" : "");
-  const { senderAllowedForCommands, commandAuthorized } = await resolveSenderCommandAuthorization({
-    cfg: config,
-    rawBody,
+  const { senderAllowedForCommands, commandAuthorized } =
+    await resolveSenderCommandAuthorizationWithRuntime({
+      cfg: config,
+      rawBody,
+      isGroup,
+      dmPolicy,
+      configuredAllowFrom: configAllowFrom,
+      configuredGroupAllowFrom: groupAllowFrom,
+      senderId,
+      isSenderAllowed: isZaloSenderAllowed,
+      readAllowFromStore: pairing.readAllowFromStore,
+      runtime: core.channel.commands,
+    });
+
+  const directDmOutcome = resolveDirectDmAuthorizationOutcome({
     isGroup,
     dmPolicy,
-    configuredAllowFrom: configAllowFrom,
-    senderId,
-    isSenderAllowed: isZaloSenderAllowed,
-    readAllowFromStore: () => core.channel.pairing.readAllowFromStore("zalo"),
-    shouldComputeCommandAuthorized: (body, cfg) =>
-      core.channel.commands.shouldComputeCommandAuthorized(body, cfg),
-    resolveCommandAuthorizedFromAuthorizers: (params) =>
-      core.channel.commands.resolveCommandAuthorizedFromAuthorizers(params),
+    senderAllowedForCommands,
   });
-
-  if (!isGroup) {
-    if (dmPolicy === "disabled") {
-      logVerbose(core, runtime, `Blocked zalo DM from ${senderId} (dmPolicy=disabled)`);
-      return;
-    }
-
-    if (dmPolicy !== "open") {
-      const allowed = senderAllowedForCommands;
-
-      if (!allowed) {
-        if (dmPolicy === "pairing") {
-          const { code, created } = await core.channel.pairing.upsertPairingRequest({
-            channel: "zalo",
-            id: senderId,
-            meta: { name: senderName ?? undefined },
-          });
-
-          if (created) {
-            logVerbose(core, runtime, `zalo pairing request sender=${senderId}`);
-            try {
-              await sendMessage(
-                token,
-                {
-                  chat_id: chatId,
-                  text: core.channel.pairing.buildPairingReply({
-                    channel: "zalo",
-                    idLine: `Your Zalo user id: ${senderId}`,
-                    code,
-                  }),
-                },
-                fetcher,
-              );
-              statusSink?.({ lastOutboundAt: Date.now() });
-            } catch (err) {
-              logVerbose(
-                core,
-                runtime,
-                `zalo pairing reply failed for ${senderId}: ${String(err)}`,
-              );
-            }
-          }
-        } else {
-          logVerbose(
-            core,
-            runtime,
-            `Blocked unauthorized zalo sender ${senderId} (dmPolicy=${dmPolicy})`,
+  if (directDmOutcome === "disabled") {
+    logVerbose(core, runtime, `Blocked zalo DM from ${senderId} (dmPolicy=disabled)`);
+    return;
+  }
+  if (directDmOutcome === "unauthorized") {
+    if (dmPolicy === "pairing") {
+      const { code, created } = await pairing.upsertPairingRequest({
+        id: senderId,
+        meta: { name: senderName ?? undefined },
+      });
+
+      if (created) {
+        logVerbose(core, runtime, `zalo pairing request sender=${senderId}`);
+        try {
+          await sendMessage(
+            token,
+            {
+              chat_id: chatId,
+              text: core.channel.pairing.buildPairingReply({
+                channel: "zalo",
+                idLine: `Your Zalo user id: ${senderId}`,
+                code,
+              }),
+            },
+            fetcher,
           );
+          statusSink?.({ lastOutboundAt: Date.now() });
+        } catch (err) {
+          logVerbose(core, runtime, `zalo pairing reply failed for ${senderId}: ${String(err)}`);
         }
-        return;
       }
+    } else {
+      logVerbose(
+        core,
+        runtime,
+        `Blocked unauthorized zalo sender ${senderId} (dmPolicy=${dmPolicy})`,
+      );
     }
+    return;
   }
 
-  const route = core.channel.routing.resolveAgentRoute({
+  const { route, buildEnvelope } = resolveInboundRouteEnvelopeBuilderWithRuntime({
     cfg: config,
     channel: "zalo",
     accountId: account.accountId,
     peer: {
-      kind: isGroup ? "group" : "direct",
+      kind: isGroup ? ("group" as const) : ("direct" as const),
       id: chatId,
     },
+    runtime: core.channel,
+    sessionStore: config.session?.store,
   });
 
   if (
@@ -437,20 +467,10 @@ async function processMessageWithPipeline(params: {
   }
 
   const fromLabel = isGroup ? `group:${chatId}` : senderName || `user:${senderId}`;
-  const storePath = core.channel.session.resolveStorePath(config.session?.store, {
-    agentId: route.agentId,
-  });
-  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config);
-  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
-    storePath,
-    sessionKey: route.sessionKey,
-  });
-  const body = core.channel.reply.formatAgentEnvelope({
+  const { storePath, body } = buildEnvelope({
     channel: "Zalo",
     from: fromLabel,
     timestamp: date ? date * 1000 : undefined,
-    previousTimestamp,
-    envelope: envelopeOptions,
     body: rawBody,
   });