@openclaw/zalo 2026.1.29

package/src/monitor.webhook.test.ts

@@ -0,0 +1,70 @@
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+
+import { describe, expect, it } from "vitest";
+
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+import type { ResolvedZaloAccount } from "./types.js";
+import { handleZaloWebhookRequest, registerZaloWebhookTarget } from "./monitor.js";
+
+async function withServer(
+  handler: Parameters<typeof createServer>[0],
+  fn: (baseUrl: string) => Promise<void>,
+) {
+  const server = createServer(handler);
+  await new Promise<void>((resolve) => {
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  const address = server.address() as AddressInfo | null;
+  if (!address) throw new Error("missing server address");
+  try {
+    await fn(`http://127.0.0.1:${address.port}`);
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+}
+
+describe("handleZaloWebhookRequest", () => {
+  it("returns 400 for non-object payloads", async () => {
+    const core = {} as PluginRuntime;
+    const account: ResolvedZaloAccount = {
+      accountId: "default",
+      enabled: true,
+      token: "tok",
+      tokenSource: "config",
+      config: {},
+    };
+    const unregister = registerZaloWebhookTarget({
+      token: "tok",
+      account,
+      config: {} as OpenClawConfig,
+      runtime: {},
+      core,
+      secret: "secret",
+      path: "/hook",
+      mediaMaxMb: 5,
+    });
+
+    try {
+      await withServer(async (req, res) => {
+        const handled = await handleZaloWebhookRequest(req, res);
+        if (!handled) {
+          res.statusCode = 404;
+          res.end("not found");
+        }
+      }, async (baseUrl) => {
+        const response = await fetch(`${baseUrl}/hook`, {
+          method: "POST",
+          headers: {
+            "x-bot-api-secret-token": "secret",
+          },
+          body: "null",
+        });
+
+        expect(response.status).toBe(400);
+      });
+    } finally {
+      unregister();
+    }
+  });
+});

package/src/onboarding.ts

@@ -0,0 +1,405 @@
+import type {
+  ChannelOnboardingAdapter,
+  ChannelOnboardingDmPolicy,
+  OpenClawConfig,
+  WizardPrompter,
+} from "openclaw/plugin-sdk";
+import {
+  addWildcardAllowFrom,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  promptAccountId,
+} from "openclaw/plugin-sdk";
+
+import {
+  listZaloAccountIds,
+  resolveDefaultZaloAccountId,
+  resolveZaloAccount,
+} from "./accounts.js";
+
+const channel = "zalo" as const;
+
+type UpdateMode = "polling" | "webhook";
+
+function setZaloDmPolicy(
+  cfg: OpenClawConfig,
+  dmPolicy: "pairing" | "allowlist" | "open" | "disabled",
+) {
+  const allowFrom = dmPolicy === "open" ? addWildcardAllowFrom(cfg.channels?.zalo?.allowFrom) : undefined;
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      zalo: {
+        ...cfg.channels?.zalo,
+        dmPolicy,
+        ...(allowFrom ? { allowFrom } : {}),
+      },
+    },
+  } as OpenClawConfig;
+}
+
+function setZaloUpdateMode(
+  cfg: OpenClawConfig,
+  accountId: string,
+  mode: UpdateMode,
+  webhookUrl?: string,
+  webhookSecret?: string,
+  webhookPath?: string,
+): OpenClawConfig {
+  const isDefault = accountId === DEFAULT_ACCOUNT_ID;
+  if (mode === "polling") {
+    if (isDefault) {
+      const {
+        webhookUrl: _url,
+        webhookSecret: _secret,
+        webhookPath: _path,
+        ...rest
+      } = cfg.channels?.zalo ?? {};
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          zalo: rest,
+        },
+      } as OpenClawConfig;
+    }
+    const accounts = { ...(cfg.channels?.zalo?.accounts ?? {}) } as Record<
+      string,
+      Record<string, unknown>
+    >;
+    const existing = accounts[accountId] ?? {};
+    const {
+      webhookUrl: _url,
+      webhookSecret: _secret,
+      webhookPath: _path,
+      ...rest
+    } = existing;
+    accounts[accountId] = rest;
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalo: {
+          ...cfg.channels?.zalo,
+          accounts,
+        },
+      },
+    } as OpenClawConfig;
+  }
+
+  if (isDefault) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalo: {
+          ...cfg.channels?.zalo,
+          webhookUrl,
+          webhookSecret,
+          webhookPath,
+        },
+      },
+    } as OpenClawConfig;
+  }
+
+  const accounts = { ...(cfg.channels?.zalo?.accounts ?? {}) } as Record<
+    string,
+    Record<string, unknown>
+  >;
+  accounts[accountId] = {
+    ...(accounts[accountId] ?? {}),
+    webhookUrl,
+    webhookSecret,
+    webhookPath,
+  };
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      zalo: {
+        ...cfg.channels?.zalo,
+        accounts,
+      },
+    },
+  } as OpenClawConfig;
+}
+
+async function noteZaloTokenHelp(prompter: WizardPrompter): Promise<void> {
+  await prompter.note(
+    [
+      "1) Open Zalo Bot Platform: https://bot.zaloplatforms.com",
+      "2) Create a bot and get the token",
+      "3) Token looks like 12345689:abc-xyz",
+      "Tip: you can also set ZALO_BOT_TOKEN in your env.",
+      "Docs: https://docs.openclaw.ai/channels/zalo",
+    ].join("\n"),
+    "Zalo bot token",
+  );
+}
+
+async function promptZaloAllowFrom(params: {
+  cfg: OpenClawConfig;
+  prompter: WizardPrompter;
+  accountId: string;
+}): Promise<OpenClawConfig> {
+  const { cfg, prompter, accountId } = params;
+  const resolved = resolveZaloAccount({ cfg, accountId });
+  const existingAllowFrom = resolved.config.allowFrom ?? [];
+  const entry = await prompter.text({
+    message: "Zalo allowFrom (user id)",
+    placeholder: "123456789",
+    initialValue: existingAllowFrom[0] ? String(existingAllowFrom[0]) : undefined,
+    validate: (value) => {
+      const raw = String(value ?? "").trim();
+      if (!raw) return "Required";
+      if (!/^\d+$/.test(raw)) return "Use a numeric Zalo user id";
+      return undefined;
+    },
+  });
+  const normalized = String(entry).trim();
+  const merged = [
+    ...existingAllowFrom.map((item) => String(item).trim()).filter(Boolean),
+    normalized,
+  ];
+  const unique = [...new Set(merged)];
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalo: {
+          ...cfg.channels?.zalo,
+          enabled: true,
+          dmPolicy: "allowlist",
+          allowFrom: unique,
+        },
+      },
+    } as OpenClawConfig;
+  }
+
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      zalo: {
+        ...cfg.channels?.zalo,
+        enabled: true,
+        accounts: {
+          ...(cfg.channels?.zalo?.accounts ?? {}),
+          [accountId]: {
+            ...(cfg.channels?.zalo?.accounts?.[accountId] ?? {}),
+            enabled: cfg.channels?.zalo?.accounts?.[accountId]?.enabled ?? true,
+            dmPolicy: "allowlist",
+            allowFrom: unique,
+          },
+        },
+      },
+    },
+  } as OpenClawConfig;
+}
+
+const dmPolicy: ChannelOnboardingDmPolicy = {
+  label: "Zalo",
+  channel,
+  policyKey: "channels.zalo.dmPolicy",
+  allowFromKey: "channels.zalo.allowFrom",
+  getCurrent: (cfg) => (cfg.channels?.zalo?.dmPolicy ?? "pairing") as "pairing",
+  setPolicy: (cfg, policy) => setZaloDmPolicy(cfg as OpenClawConfig, policy),
+  promptAllowFrom: async ({ cfg, prompter, accountId }) => {
+    const id =
+      accountId && normalizeAccountId(accountId)
+        ? normalizeAccountId(accountId) ?? DEFAULT_ACCOUNT_ID
+        : resolveDefaultZaloAccountId(cfg as OpenClawConfig);
+    return promptZaloAllowFrom({
+      cfg: cfg as OpenClawConfig,
+      prompter,
+      accountId: id,
+    });
+  },
+};
+
+export const zaloOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  dmPolicy,
+  getStatus: async ({ cfg }) => {
+    const configured = listZaloAccountIds(cfg as OpenClawConfig).some((accountId) =>
+      Boolean(resolveZaloAccount({ cfg: cfg as OpenClawConfig, accountId }).token),
+    );
+    return {
+      channel,
+      configured,
+      statusLines: [`Zalo: ${configured ? "configured" : "needs token"}`],
+      selectionHint: configured ? "recommended · configured" : "recommended · newcomer-friendly",
+      quickstartScore: configured ? 1 : 10,
+    };
+  },
+  configure: async ({ cfg, prompter, accountOverrides, shouldPromptAccountIds, forceAllowFrom }) => {
+    const zaloOverride = accountOverrides.zalo?.trim();
+    const defaultZaloAccountId = resolveDefaultZaloAccountId(cfg as OpenClawConfig);
+    let zaloAccountId = zaloOverride
+      ? normalizeAccountId(zaloOverride)
+      : defaultZaloAccountId;
+    if (shouldPromptAccountIds && !zaloOverride) {
+      zaloAccountId = await promptAccountId({
+        cfg: cfg as OpenClawConfig,
+        prompter,
+        label: "Zalo",
+        currentId: zaloAccountId,
+        listAccountIds: listZaloAccountIds,
+        defaultAccountId: defaultZaloAccountId,
+      });
+    }
+
+    let next = cfg as OpenClawConfig;
+    const resolvedAccount = resolveZaloAccount({ cfg: next, accountId: zaloAccountId });
+    const accountConfigured = Boolean(resolvedAccount.token);
+    const allowEnv = zaloAccountId === DEFAULT_ACCOUNT_ID;
+    const canUseEnv = allowEnv && Boolean(process.env.ZALO_BOT_TOKEN?.trim());
+    const hasConfigToken = Boolean(
+      resolvedAccount.config.botToken || resolvedAccount.config.tokenFile,
+    );
+
+    let token: string | null = null;
+    if (!accountConfigured) {
+      await noteZaloTokenHelp(prompter);
+    }
+    if (canUseEnv && !resolvedAccount.config.botToken) {
+      const keepEnv = await prompter.confirm({
+        message: "ZALO_BOT_TOKEN detected. Use env var?",
+        initialValue: true,
+      });
+      if (keepEnv) {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            zalo: {
+              ...next.channels?.zalo,
+              enabled: true,
+            },
+          },
+        } as OpenClawConfig;
+      } else {
+        token = String(
+          await prompter.text({
+            message: "Enter Zalo bot token",
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+          }),
+        ).trim();
+      }
+    } else if (hasConfigToken) {
+      const keep = await prompter.confirm({
+        message: "Zalo token already configured. Keep it?",
+        initialValue: true,
+      });
+      if (!keep) {
+        token = String(
+          await prompter.text({
+            message: "Enter Zalo bot token",
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+          }),
+        ).trim();
+      }
+    } else {
+      token = String(
+        await prompter.text({
+          message: "Enter Zalo bot token",
+          validate: (value) => (value?.trim() ? undefined : "Required"),
+        }),
+      ).trim();
+    }
+
+    if (token) {
+      if (zaloAccountId === DEFAULT_ACCOUNT_ID) {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            zalo: {
+              ...next.channels?.zalo,
+              enabled: true,
+              botToken: token,
+            },
+          },
+        } as OpenClawConfig;
+      } else {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            zalo: {
+              ...next.channels?.zalo,
+              enabled: true,
+              accounts: {
+                ...(next.channels?.zalo?.accounts ?? {}),
+                [zaloAccountId]: {
+                  ...(next.channels?.zalo?.accounts?.[zaloAccountId] ?? {}),
+                  enabled: true,
+                  botToken: token,
+                },
+              },
+            },
+          },
+        } as OpenClawConfig;
+      }
+    }
+
+    const wantsWebhook = await prompter.confirm({
+      message: "Use webhook mode for Zalo?",
+      initialValue: false,
+    });
+    if (wantsWebhook) {
+      const webhookUrl = String(
+        await prompter.text({
+          message: "Webhook URL (https://...) ",
+          validate: (value) => (value?.trim()?.startsWith("https://") ? undefined : "HTTPS URL required"),
+        }),
+      ).trim();
+      const defaultPath = (() => {
+        try {
+          return new URL(webhookUrl).pathname || "/zalo-webhook";
+        } catch {
+          return "/zalo-webhook";
+        }
+      })();
+      const webhookSecret = String(
+        await prompter.text({
+          message: "Webhook secret (8-256 chars)",
+          validate: (value) => {
+            const raw = String(value ?? "");
+            if (raw.length < 8 || raw.length > 256) return "8-256 chars";
+            return undefined;
+          },
+        }),
+      ).trim();
+      const webhookPath = String(
+        await prompter.text({
+          message: "Webhook path (optional)",
+          initialValue: defaultPath,
+        }),
+      ).trim();
+      next = setZaloUpdateMode(
+        next,
+        zaloAccountId,
+        "webhook",
+        webhookUrl,
+        webhookSecret,
+        webhookPath || undefined,
+      );
+    } else {
+      next = setZaloUpdateMode(next, zaloAccountId, "polling");
+    }
+
+    if (forceAllowFrom) {
+      next = await promptZaloAllowFrom({
+        cfg: next,
+        prompter,
+        accountId: zaloAccountId,
+      });
+    }
+
+    return { cfg: next, accountId: zaloAccountId };
+  },
+};

package/src/probe.ts

@@ -0,0 +1,46 @@
+import { getMe, ZaloApiError, type ZaloBotInfo, type ZaloFetch } from "./api.js";
+
+export type ZaloProbeResult = {
+  ok: boolean;
+  bot?: ZaloBotInfo;
+  error?: string;
+  elapsedMs: number;
+};
+
+export async function probeZalo(
+  token: string,
+  timeoutMs = 5000,
+  fetcher?: ZaloFetch,
+): Promise<ZaloProbeResult> {
+  if (!token?.trim()) {
+    return { ok: false, error: "No token provided", elapsedMs: 0 };
+  }
+
+  const startTime = Date.now();
+
+  try {
+    const response = await getMe(token.trim(), timeoutMs, fetcher);
+    const elapsedMs = Date.now() - startTime;
+
+    if (response.ok && response.result) {
+      return { ok: true, bot: response.result, elapsedMs };
+    }
+
+    return { ok: false, error: "Invalid response from Zalo API", elapsedMs };
+  } catch (err) {
+    const elapsedMs = Date.now() - startTime;
+
+    if (err instanceof ZaloApiError) {
+      return { ok: false, error: err.description ?? err.message, elapsedMs };
+    }
+
+    if (err instanceof Error) {
+      if (err.name === "AbortError") {
+        return { ok: false, error: `Request timed out after ${timeoutMs}ms`, elapsedMs };
+      }
+      return { ok: false, error: err.message, elapsedMs };
+    }
+
+    return { ok: false, error: String(err), elapsedMs };
+  }
+}

package/src/proxy.ts

@@ -0,0 +1,18 @@
+import { ProxyAgent, fetch as undiciFetch } from "undici";
+import type { Dispatcher } from "undici";
+
+import type { ZaloFetch } from "./api.js";
+
+const proxyCache = new Map<string, ZaloFetch>();
+
+export function resolveZaloProxyFetch(proxyUrl?: string | null): ZaloFetch | undefined {
+  const trimmed = proxyUrl?.trim();
+  if (!trimmed) return undefined;
+  const cached = proxyCache.get(trimmed);
+  if (cached) return cached;
+  const agent = new ProxyAgent(trimmed);
+  const fetcher: ZaloFetch = (input, init) =>
+    undiciFetch(input, { ...(init ?? {}), dispatcher: agent as Dispatcher });
+  proxyCache.set(trimmed, fetcher);
+  return fetcher;
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setZaloRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getZaloRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Zalo runtime not initialized");
+  }
+  return runtime;
+}

package/src/send.ts

@@ -0,0 +1,117 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+import type { ZaloFetch } from "./api.js";
+import { sendMessage, sendPhoto } from "./api.js";
+import { resolveZaloAccount } from "./accounts.js";
+import { resolveZaloProxyFetch } from "./proxy.js";
+import { resolveZaloToken } from "./token.js";
+
+export type ZaloSendOptions = {
+  token?: string;
+  accountId?: string;
+  cfg?: OpenClawConfig;
+  mediaUrl?: string;
+  caption?: string;
+  verbose?: boolean;
+  proxy?: string;
+};
+
+export type ZaloSendResult = {
+  ok: boolean;
+  messageId?: string;
+  error?: string;
+};
+
+function resolveSendContext(options: ZaloSendOptions): {
+  token: string;
+  fetcher?: ZaloFetch;
+} {
+  if (options.cfg) {
+    const account = resolveZaloAccount({
+      cfg: options.cfg,
+      accountId: options.accountId,
+    });
+    const token = options.token || account.token;
+    const proxy = options.proxy ?? account.config.proxy;
+    return { token, fetcher: resolveZaloProxyFetch(proxy) };
+  }
+
+  const token = options.token ?? resolveZaloToken(undefined, options.accountId).token;
+  const proxy = options.proxy;
+  return { token, fetcher: resolveZaloProxyFetch(proxy) };
+}
+
+export async function sendMessageZalo(
+  chatId: string,
+  text: string,
+  options: ZaloSendOptions = {},
+): Promise<ZaloSendResult> {
+  const { token, fetcher } = resolveSendContext(options);
+
+  if (!token) {
+    return { ok: false, error: "No Zalo bot token configured" };
+  }
+
+  if (!chatId?.trim()) {
+    return { ok: false, error: "No chat_id provided" };
+  }
+
+  if (options.mediaUrl) {
+    return sendPhotoZalo(chatId, options.mediaUrl, {
+      ...options,
+      token,
+      caption: text || options.caption,
+    });
+  }
+
+  try {
+    const response = await sendMessage(token, {
+      chat_id: chatId.trim(),
+      text: text.slice(0, 2000),
+    }, fetcher);
+
+    if (response.ok && response.result) {
+      return { ok: true, messageId: response.result.message_id };
+    }
+
+    return { ok: false, error: "Failed to send message" };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export async function sendPhotoZalo(
+  chatId: string,
+  photoUrl: string,
+  options: ZaloSendOptions = {},
+): Promise<ZaloSendResult> {
+  const { token, fetcher } = resolveSendContext(options);
+
+  if (!token) {
+    return { ok: false, error: "No Zalo bot token configured" };
+  }
+
+  if (!chatId?.trim()) {
+    return { ok: false, error: "No chat_id provided" };
+  }
+
+  if (!photoUrl?.trim()) {
+    return { ok: false, error: "No photo URL provided" };
+  }
+
+  try {
+    const response = await sendPhoto(token, {
+      chat_id: chatId.trim(),
+      photo: photoUrl.trim(),
+      caption: options.caption?.slice(0, 2000),
+    }, fetcher);
+
+    if (response.ok && response.result) {
+      return { ok: true, messageId: response.result.message_id };
+    }
+
+    return { ok: false, error: "Failed to send photo" };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}