@openclaw/zalo 2026.1.29

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+## 2026.1.29
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.23
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.22
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.21
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.20
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.17-1
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.17
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.16
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.15
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.14
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 0.1.0
+
+### Features
+- Zalo Bot API channel plugin with token-based auth (env/config/file).
+- Direct message support (DMs only) with pairing/allowlist/open/disabled policies.
+- Polling and webhook delivery modes.
+- Text + image messaging with 2000-char chunking and media size caps.
+- Multi-account support with per-account config.

package/README.md

@@ -0,0 +1,50 @@
+# @openclaw/zalo
+
+Zalo channel plugin for OpenClaw (Bot API).
+
+## Install (local checkout)
+
+```bash
+openclaw plugins install ./extensions/zalo
+```
+
+## Install (npm)
+
+```bash
+openclaw plugins install @openclaw/zalo
+```
+
+Onboarding: select Zalo and confirm the install prompt to fetch the plugin automatically.
+
+## Config
+
+```json5
+{
+  channels: {
+    zalo: {
+      enabled: true,
+      botToken: "12345689:abc-xyz",
+      dmPolicy: "pairing",
+      proxy: "http://proxy.local:8080"
+    }
+  }
+}
+```
+
+## Webhook mode
+
+```json5
+{
+  channels: {
+    zalo: {
+      webhookUrl: "https://example.com/zalo-webhook",
+      webhookSecret: "your-secret-8-plus-chars",
+      webhookPath: "/zalo-webhook"
+    }
+  }
+}
+```
+
+If `webhookPath` is omitted, the plugin uses the webhook URL path.
+
+Restart the gateway after config changes.

package/index.ts

@@ -0,0 +1,20 @@
+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 = {
+  id: "zalo",
+  name: "Zalo",
+  description: "Zalo channel plugin (Bot API)",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setZaloRuntime(api.runtime);
+    api.registerChannel({ plugin: zaloPlugin, dock: zaloDock });
+    api.registerHttpHandler(handleZaloWebhookRequest);
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "zalo",
+  "channels": [
+    "zalo"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@openclaw/zalo",
+  "version": "2026.1.29",
+  "type": "module",
+  "description": "OpenClaw Zalo channel plugin",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "zalo",
+      "label": "Zalo",
+      "selectionLabel": "Zalo (Bot API)",
+      "docsPath": "/channels/zalo",
+      "docsLabel": "zalo",
+      "blurb": "Vietnam-focused messaging platform with Bot API.",
+      "aliases": [
+        "zl"
+      ],
+      "order": 80,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "@openclaw/zalo",
+      "localPath": "extensions/zalo",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "openclaw": "workspace:*",
+    "undici": "7.19.0"
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,71 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk";
+
+import type { ResolvedZaloAccount, ZaloAccountConfig, ZaloConfig } from "./types.js";
+import { resolveZaloToken } from "./token.js";
+
+function listConfiguredAccountIds(cfg: OpenClawConfig): string[] {
+  const accounts = (cfg.channels?.zalo as ZaloConfig | undefined)?.accounts;
+  if (!accounts || typeof accounts !== "object") return [];
+  return Object.keys(accounts).filter(Boolean);
+}
+
+export function listZaloAccountIds(cfg: OpenClawConfig): string[] {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
+  return ids.sort((a, b) => a.localeCompare(b));
+}
+
+export function resolveDefaultZaloAccountId(cfg: OpenClawConfig): string {
+  const zaloConfig = cfg.channels?.zalo as ZaloConfig | undefined;
+  if (zaloConfig?.defaultAccount?.trim()) return zaloConfig.defaultAccount.trim();
+  const ids = listZaloAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+function resolveAccountConfig(
+  cfg: OpenClawConfig,
+  accountId: string,
+): ZaloAccountConfig | undefined {
+  const accounts = (cfg.channels?.zalo as ZaloConfig | undefined)?.accounts;
+  if (!accounts || typeof accounts !== "object") return undefined;
+  return accounts[accountId] as ZaloAccountConfig | undefined;
+}
+
+function mergeZaloAccountConfig(cfg: OpenClawConfig, accountId: string): ZaloAccountConfig {
+  const raw = (cfg.channels?.zalo ?? {}) as ZaloConfig;
+  const { accounts: _ignored, defaultAccount: _ignored2, ...base } = raw;
+  const account = resolveAccountConfig(cfg, accountId) ?? {};
+  return { ...base, ...account };
+}
+
+export function resolveZaloAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): ResolvedZaloAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const baseEnabled = (params.cfg.channels?.zalo as ZaloConfig | undefined)?.enabled !== false;
+  const merged = mergeZaloAccountConfig(params.cfg, accountId);
+  const accountEnabled = merged.enabled !== false;
+  const enabled = baseEnabled && accountEnabled;
+  const tokenResolution = resolveZaloToken(
+    params.cfg.channels?.zalo as ZaloConfig | undefined,
+    accountId,
+  );
+
+  return {
+    accountId,
+    name: merged.name?.trim() || undefined,
+    enabled,
+    token: tokenResolution.token,
+    tokenSource: tokenResolution.source,
+    config: merged,
+  };
+}
+
+export function listEnabledZaloAccounts(cfg: OpenClawConfig): ResolvedZaloAccount[] {
+  return listZaloAccountIds(cfg)
+    .map((accountId) => resolveZaloAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}

package/src/actions.ts

@@ -0,0 +1,62 @@
+import type {
+  ChannelMessageActionAdapter,
+  ChannelMessageActionName,
+  OpenClawConfig,
+} from "openclaw/plugin-sdk";
+import { jsonResult, readStringParam } from "openclaw/plugin-sdk";
+
+import { listEnabledZaloAccounts } from "./accounts.js";
+import { sendMessageZalo } from "./send.js";
+
+const providerId = "zalo";
+
+function listEnabledAccounts(cfg: OpenClawConfig) {
+  return listEnabledZaloAccounts(cfg).filter(
+    (account) => account.enabled && account.tokenSource !== "none",
+  );
+}
+
+export const zaloMessageActions: ChannelMessageActionAdapter = {
+  listActions: ({ cfg }) => {
+    const accounts = listEnabledAccounts(cfg as OpenClawConfig);
+    if (accounts.length === 0) return [];
+    const actions = new Set<ChannelMessageActionName>(["send"]);
+    return Array.from(actions);
+  },
+  supportsButtons: () => false,
+  extractToolSend: ({ args }) => {
+    const action = typeof args.action === "string" ? args.action.trim() : "";
+    if (action !== "sendMessage") return null;
+    const to = typeof args.to === "string" ? args.to : undefined;
+    if (!to) return null;
+    const accountId = typeof args.accountId === "string" ? args.accountId.trim() : undefined;
+    return { to, accountId };
+  },
+  handleAction: async ({ action, params, cfg, accountId }) => {
+    if (action === "send") {
+      const to = readStringParam(params, "to", { required: true });
+      const content = readStringParam(params, "message", {
+        required: true,
+        allowEmpty: true,
+      });
+      const mediaUrl = readStringParam(params, "media", { trim: false });
+
+      const result = await sendMessageZalo(to ?? "", content ?? "", {
+        accountId: accountId ?? undefined,
+        mediaUrl: mediaUrl ?? undefined,
+        cfg: cfg as OpenClawConfig,
+      });
+
+      if (!result.ok) {
+        return jsonResult({
+          ok: false,
+          error: result.error ?? "Failed to send Zalo message",
+        });
+      }
+
+      return jsonResult({ ok: true, to, messageId: result.messageId });
+    }
+
+    throw new Error(`Action ${action} is not supported for provider ${providerId}.`);
+  },
+};

package/src/api.ts

@@ -0,0 +1,206 @@
+/**
+ * Zalo Bot API client
+ * @see https://bot.zaloplatforms.com/docs
+ */
+
+const ZALO_API_BASE = "https://bot-api.zaloplatforms.com";
+
+export type ZaloFetch = (input: string, init?: RequestInit) => Promise<Response>;
+
+export type ZaloApiResponse<T = unknown> = {
+  ok: boolean;
+  result?: T;
+  error_code?: number;
+  description?: string;
+};
+
+export type ZaloBotInfo = {
+  id: string;
+  name: string;
+  avatar?: string;
+};
+
+export type ZaloMessage = {
+  message_id: string;
+  from: {
+    id: string;
+    name?: string;
+    avatar?: string;
+  };
+  chat: {
+    id: string;
+    chat_type: "PRIVATE" | "GROUP";
+  };
+  date: number;
+  text?: string;
+  photo?: string;
+  caption?: string;
+  sticker?: string;
+};
+
+export type ZaloUpdate = {
+  event_name:
+    | "message.text.received"
+    | "message.image.received"
+    | "message.sticker.received"
+    | "message.unsupported.received";
+  message?: ZaloMessage;
+};
+
+export type ZaloSendMessageParams = {
+  chat_id: string;
+  text: string;
+};
+
+export type ZaloSendPhotoParams = {
+  chat_id: string;
+  photo: string;
+  caption?: string;
+};
+
+export type ZaloSetWebhookParams = {
+  url: string;
+  secret_token: string;
+};
+
+export type ZaloGetUpdatesParams = {
+  /** Timeout in seconds (passed as string to API) */
+  timeout?: number;
+};
+
+export class ZaloApiError extends Error {
+  constructor(
+    message: string,
+    public readonly errorCode?: number,
+    public readonly description?: string,
+  ) {
+    super(message);
+    this.name = "ZaloApiError";
+  }
+
+  /** True if this is a long-polling timeout (no updates available) */
+  get isPollingTimeout(): boolean {
+    return this.errorCode === 408;
+  }
+}
+
+/**
+ * Call the Zalo Bot API
+ */
+export async function callZaloApi<T = unknown>(
+  method: string,
+  token: string,
+  body?: Record<string, unknown>,
+  options?: { timeoutMs?: number; fetch?: ZaloFetch },
+): Promise<ZaloApiResponse<T>> {
+  const url = `${ZALO_API_BASE}/bot${token}/${method}`;
+  const controller = new AbortController();
+  const timeoutId = options?.timeoutMs
+    ? setTimeout(() => controller.abort(), options.timeoutMs)
+    : undefined;
+  const fetcher = options?.fetch ?? fetch;
+
+  try {
+    const response = await fetcher(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: controller.signal,
+    });
+
+    const data = (await response.json()) as ZaloApiResponse<T>;
+
+    if (!data.ok) {
+      throw new ZaloApiError(
+        data.description ?? `Zalo API error: ${method}`,
+        data.error_code,
+        data.description,
+      );
+    }
+
+    return data;
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+}
+
+/**
+ * Validate bot token and get bot info
+ */
+export async function getMe(
+  token: string,
+  timeoutMs?: number,
+  fetcher?: ZaloFetch,
+): Promise<ZaloApiResponse<ZaloBotInfo>> {
+  return callZaloApi<ZaloBotInfo>("getMe", token, undefined, { timeoutMs, fetch: fetcher });
+}
+
+/**
+ * Send a text message
+ */
+export async function sendMessage(
+  token: string,
+  params: ZaloSendMessageParams,
+  fetcher?: ZaloFetch,
+): Promise<ZaloApiResponse<ZaloMessage>> {
+  return callZaloApi<ZaloMessage>("sendMessage", token, params, { fetch: fetcher });
+}
+
+/**
+ * Send a photo message
+ */
+export async function sendPhoto(
+  token: string,
+  params: ZaloSendPhotoParams,
+  fetcher?: ZaloFetch,
+): Promise<ZaloApiResponse<ZaloMessage>> {
+  return callZaloApi<ZaloMessage>("sendPhoto", token, params, { fetch: fetcher });
+}
+
+/**
+ * Get updates using long polling (dev/testing only)
+ * Note: Zalo returns a single update per call, not an array like Telegram
+ */
+export async function getUpdates(
+  token: string,
+  params?: ZaloGetUpdatesParams,
+  fetcher?: ZaloFetch,
+): Promise<ZaloApiResponse<ZaloUpdate>> {
+  const pollTimeoutSec = params?.timeout ?? 30;
+  const timeoutMs = (pollTimeoutSec + 5) * 1000;
+  const body = { timeout: String(pollTimeoutSec) };
+  return callZaloApi<ZaloUpdate>("getUpdates", token, body, { timeoutMs, fetch: fetcher });
+}
+
+/**
+ * Set webhook URL for receiving updates
+ */
+export async function setWebhook(
+  token: string,
+  params: ZaloSetWebhookParams,
+  fetcher?: ZaloFetch,
+): Promise<ZaloApiResponse<boolean>> {
+  return callZaloApi<boolean>("setWebhook", token, params, { fetch: fetcher });
+}
+
+/**
+ * Delete webhook configuration
+ */
+export async function deleteWebhook(
+  token: string,
+  fetcher?: ZaloFetch,
+): Promise<ZaloApiResponse<boolean>> {
+  return callZaloApi<boolean>("deleteWebhook", token, undefined, { fetch: fetcher });
+}
+
+/**
+ * Get current webhook info
+ */
+export async function getWebhookInfo(
+  token: string,
+  fetcher?: ZaloFetch,
+): Promise<ZaloApiResponse<{ url?: string; has_custom_certificate?: boolean }>> {
+  return callZaloApi("getWebhookInfo", token, undefined, { fetch: fetcher });
+}

package/src/channel.directory.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+import { zaloPlugin } from "./channel.js";
+
+describe("zalo directory", () => {
+  it("lists peers from allowFrom", async () => {
+    const cfg = {
+      channels: {
+        zalo: {
+          allowFrom: ["zalo:123", "zl:234", "345"],
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    expect(zaloPlugin.directory).toBeTruthy();
+    expect(zaloPlugin.directory?.listPeers).toBeTruthy();
+    expect(zaloPlugin.directory?.listGroups).toBeTruthy();
+
+    await expect(
+      zaloPlugin.directory!.listPeers({ cfg, accountId: undefined, query: undefined, limit: undefined }),
+    ).resolves.toEqual(
+      expect.arrayContaining([
+        { kind: "user", id: "123" },
+        { kind: "user", id: "234" },
+        { kind: "user", id: "345" },
+      ]),
+    );
+
+    await expect(zaloPlugin.directory!.listGroups({ cfg, accountId: undefined, query: undefined, limit: undefined })).resolves.toEqual(
+      [],
+    );
+  });
+});