zalo_bot 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to npm
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - run: npm install
+
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,57 @@
+# @openclaw/zalo-bot
+
+OpenClaw Zalo channel plugin (Bot API) — patched fork.
+
+## AI Install Metadata
+- Plugin id: zalo_bot
+- Channel id: zalo_bot
+- Package name: @openclaw/zalo-bot
+
+## Fixes
+
+- **`photo_url` field mapping**: Correctly parses the Zalo Bot API's `photo_url` field for image messages
+- **Image + Caption handling**: When a user sends both an image and text caption, both are now correctly forwarded to the AI agent
+
+## Install (local checkout)
+
+```bash
+# Clone the repo
+git clone https://github.com/vuminhtuanhvtc/openclaw-zalo-bot.git
+cd openclaw-zalo-bot
+
+# Install dependencies
+npm install
+
+# Register with OpenClaw
+openclaw plugins install .
+```
+
+Restart Gateway after installation.
+
+## Quick Start
+
+Add channel config to `openclaw.json`:
+
+```json
+{
+  "channels": {
+    "zalo_bot": {
+      "enabled": true,
+      "token": "YOUR_ZALO_BOT_TOKEN",
+      "webhookUrl": "https://your-domain.com/zalo_bot-webhook",
+      "webhookSecret": "your-webhook-secret",
+      "dmPolicy": "open"
+    }
+  }
+}
+```
+
+Then restart:
+
+```bash
+openclaw gateway restart
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,19 @@
+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_bot",
+  name: "Zalo Bot",
+  description: "Zalo channel plugin (Bot API) — patched fork",
+  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,9 @@
+{
+  "id": "zalo_bot",
+  "channels": ["zalo_bot"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "zalo_bot",
+  "version": "1.0.0",
+  "description": "OpenClaw Zalo channel plugin (Bot API) — patched fork with photo_url and image+caption fixes",
+  "type": "module",
+  "dependencies": {
+    "undici": "7.22.0",
+    "zod": "^4.3.6"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "zalo_bot",
+      "label": "Zalo Bot",
+      "selectionLabel": "Zalo Bot (Bot API)",
+      "docsPath": "/channels/zalo",
+      "docsLabel": "zalo_bot",
+      "blurb": "Vietnam-focused messaging platform with Bot API (patched).",
+      "aliases": [
+        "zb"
+      ],
+      "order": 81,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "zalo_bot",
+      "localPath": "extensions/zalo_bot",
+      "defaultChoice": "npm"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vuminhtuanhvtc/openclaw-zalo-bot.git"
+  },
+  "license": "MIT"
+}

package/src/accounts.ts

@@ -0,0 +1,82 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { resolveZaloToken } from "./token.js";
+import type { ResolvedZaloAccount, ZaloAccountConfig, ZaloConfig } from "./types.js";
+
+export type { ResolvedZaloAccount };
+
+function listConfiguredAccountIds(cfg: OpenClawConfig): string[] {
+  const accounts = (cfg.channels?.zalo_bot 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.toSorted((a, b) => a.localeCompare(b));
+}
+
+export function resolveDefaultZaloAccountId(cfg: OpenClawConfig): string {
+  const zaloConfig = cfg.channels?.zalo_bot 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_bot 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_bot ?? {}) 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_bot 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_bot 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,56 @@
+import type {
+  ChannelMessageActionAdapter,
+  ChannelMessageActionName,
+  OpenClawConfig,
+} from "openclaw/plugin-sdk";
+import { extractToolSend, 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);
+    if (accounts.length === 0) {
+      return [];
+    }
+    const actions = new Set<ChannelMessageActionName>(["send"]);
+    return Array.from(actions);
+  },
+  supportsButtons: () => false,
+  extractToolSend: ({ args }) => extractToolSend(args, "sendMessage"),
+  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,
+      });
+
+      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,208 @@
+/**
+ * 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_url?: 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 });
+}