@openclaw/zalo 2026.3.12 → 2026.5.1-beta.2

package/src/monitor.ts

@@ -1,25 +1,24 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type {
-  MarkdownTableMode,
-  OpenClawConfig,
-  OutboundReplyPayload,
-} from "openclaw/plugin-sdk/zalo";
+import { logTypingFailure } from "openclaw/plugin-sdk/channel-feedback";
+import { createChannelPairingController } from "openclaw/plugin-sdk/channel-pairing";
+import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
 import {
-  createTypingCallbacks,
-  createScopedPairingAccess,
-  createReplyPrefixOptions,
-  issuePairingChallenge,
-  logTypingFailure,
   resolveDirectDmAuthorizationOutcome,
   resolveSenderCommandAuthorizationWithRuntime,
-  resolveOutboundMediaUrls,
+} from "openclaw/plugin-sdk/command-auth";
+import type { MarkdownTableMode, OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { resolveInboundRouteEnvelopeBuilderWithRuntime } from "openclaw/plugin-sdk/inbound-envelope";
+import { resolveSendableOutboundReplyParts } from "openclaw/plugin-sdk/reply-payload";
+import {
+  deliverTextOrMediaReply,
+  type OutboundReplyPayload,
+} from "openclaw/plugin-sdk/reply-payload";
+import { waitForAbortSignal } from "openclaw/plugin-sdk/runtime-env";
+import {
   resolveDefaultGroupPolicy,
-  resolveInboundRouteEnvelopeBuilderWithRuntime,
-  sendMediaWithLeadingCaption,
-  resolveWebhookPath,
-  waitForAbortSignal,
   warnMissingProviderGroupPolicyFallbackOnce,
-} from "openclaw/plugin-sdk/zalo";
+} from "openclaw/plugin-sdk/runtime-group-policy";
+import { registerPluginHttpRoute, resolveWebhookPath } from "openclaw/plugin-sdk/webhook-ingress";
 import type { ResolvedZaloAccount } from "./accounts.js";
 import {
   ZaloApiError,
@@ -39,21 +38,15 @@ import {
   isZaloSenderAllowed,
   resolveZaloRuntimeGroupPolicy,
 } from "./group-access.js";
-import {
-  clearZaloWebhookSecurityStateForTest,
-  getZaloWebhookRateLimitStateSizeForTest,
-  getZaloWebhookStatusCounterSizeForTest,
-  handleZaloWebhookRequest as handleZaloWebhookRequestInternal,
-  registerZaloWebhookTarget as registerZaloWebhookTargetInternal,
-  type ZaloWebhookTarget,
-} from "./monitor.webhook.js";
 import { resolveZaloProxyFetch } from "./proxy.js";
 import { getZaloRuntime } from "./runtime.js";
-
-export type ZaloRuntimeEnv = {
-  log?: (message: string) => void;
-  error?: (message: string) => void;
-};
+export type { ZaloRuntimeEnv } from "./monitor.types.js";
+import type { ZaloRuntimeEnv } from "./monitor.types.js";
+import {
+  prepareHostedZaloMediaUrl,
+  resolveHostedZaloMediaRoutePrefix,
+  tryHandleHostedZaloMediaRequest,
+} from "./outbound-media.js";
 
 export type ZaloMonitorOptions = {
   token: string;
@@ -75,6 +68,115 @@ const WEBHOOK_CLEANUP_TIMEOUT_MS = 5_000;
 const ZALO_TYPING_TIMEOUT_MS = 5_000;
 
 type ZaloCoreRuntime = ReturnType<typeof getZaloRuntime>;
+type ZaloStatusSink = (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+type ZaloWebhookModule = typeof import("./monitor.webhook.js");
+type ZaloProcessingContext = {
+  token: string;
+  account: ResolvedZaloAccount;
+  config: OpenClawConfig;
+  runtime: ZaloRuntimeEnv;
+  core: ZaloCoreRuntime;
+  mediaMaxMb: number;
+  canHostMedia: boolean;
+  webhookUrl?: string;
+  webhookPath?: string;
+  statusSink?: ZaloStatusSink;
+  fetcher?: ZaloFetch;
+};
+type ZaloPollingLoopParams = ZaloProcessingContext & {
+  abortSignal: AbortSignal;
+  isStopped: () => boolean;
+};
+type ZaloUpdateProcessingParams = ZaloProcessingContext & {
+  update: ZaloUpdate;
+};
+
+let zaloWebhookModulePromise: Promise<ZaloWebhookModule> | undefined;
+const hostedMediaRouteRefs = new Map<string, { count: number; unregisters: Array<() => void> }>();
+
+function loadZaloWebhookModule(): Promise<ZaloWebhookModule> {
+  zaloWebhookModulePromise ??= import("./monitor.webhook.js");
+  return zaloWebhookModulePromise;
+}
+
+function registerSharedHostedMediaRoute(params: {
+  path: string;
+  accountId: string;
+  log?: (message: string) => void;
+}): () => void {
+  const unregister = registerPluginHttpRoute({
+    auth: "plugin",
+    match: "prefix",
+    path: params.path,
+    pluginId: "zalo",
+    source: "zalo-hosted-media",
+    accountId: params.accountId,
+    log: params.log,
+    handler: async (req, res) => {
+      const handled = await tryHandleHostedZaloMediaRequest(req, res);
+      if (!handled && !res.headersSent) {
+        res.statusCode = 404;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end("Not Found");
+      }
+    },
+  });
+
+  const existing = hostedMediaRouteRefs.get(params.path);
+  if (existing) {
+    existing.count += 1;
+    existing.unregisters.push(unregister);
+    return () => {
+      const current = hostedMediaRouteRefs.get(params.path);
+      if (!current) {
+        return;
+      }
+      if (current.count > 1) {
+        current.count -= 1;
+        return;
+      }
+      hostedMediaRouteRefs.delete(params.path);
+      for (const unregisterHandle of current.unregisters) {
+        unregisterHandle();
+      }
+    };
+  }
+
+  hostedMediaRouteRefs.set(params.path, { count: 1, unregisters: [unregister] });
+  return () => {
+    const current = hostedMediaRouteRefs.get(params.path);
+    if (!current) {
+      return;
+    }
+    if (current.count > 1) {
+      current.count -= 1;
+      return;
+    }
+    hostedMediaRouteRefs.delete(params.path);
+    for (const unregisterHandle of current.unregisters) {
+      unregisterHandle();
+    }
+  };
+}
+
+type ZaloMessagePipelineParams = ZaloProcessingContext & {
+  message: ZaloMessage;
+  text?: string;
+  mediaPath?: string;
+  mediaType?: string;
+  authorization?: ZaloMessageAuthorizationResult;
+};
+type ZaloImageMessageParams = ZaloProcessingContext & {
+  message: ZaloMessage;
+};
+type ZaloMessageAuthorizationResult = {
+  chatId: string;
+  commandAuthorized: boolean | undefined;
+  isGroup: boolean;
+  rawBody: string;
+  senderId: string;
+  senderName: string | undefined;
+};
 
 function formatZaloError(error: unknown): string {
   if (error instanceof Error) {
@@ -103,100 +205,79 @@ function logVerbose(core: ZaloCoreRuntime, runtime: ZaloRuntimeEnv, message: str
   }
 }
 
-export function registerZaloWebhookTarget(target: ZaloWebhookTarget): () => void {
-  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,
 ): Promise<boolean> {
-  return handleZaloWebhookRequestInternal(req, res, async ({ update, target }) => {
-    await processUpdate(
+  const { handleZaloWebhookRequest: handleZaloWebhookRequestInternal } =
+    await loadZaloWebhookModule();
+  return await handleZaloWebhookRequestInternal(req, res, async ({ update, target }) => {
+    await processUpdate({
       update,
-      target.token,
-      target.account,
-      target.config,
-      target.runtime,
-      target.core as ZaloCoreRuntime,
-      target.mediaMaxMb,
-      target.statusSink,
-      target.fetcher,
-    );
+      token: target.token,
+      account: target.account,
+      config: target.config,
+      runtime: target.runtime,
+      core: target.core as ZaloCoreRuntime,
+      mediaMaxMb: target.mediaMaxMb,
+      canHostMedia: target.canHostMedia,
+      webhookUrl: target.webhookUrl,
+      webhookPath: target.webhookPath,
+      statusSink: target.statusSink,
+      fetcher: target.fetcher,
+    });
   });
 }
 
-function startPollingLoop(params: {
-  token: string;
-  account: ResolvedZaloAccount;
-  config: OpenClawConfig;
-  runtime: ZaloRuntimeEnv;
-  core: ZaloCoreRuntime;
-  abortSignal: AbortSignal;
-  isStopped: () => boolean;
-  mediaMaxMb: number;
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
-  fetcher?: ZaloFetch;
-}) {
+function startPollingLoop(params: ZaloPollingLoopParams) {
   const {
     token,
     account,
     config,
     runtime,
     core,
+    mediaMaxMb,
+    canHostMedia,
+    webhookUrl,
+    webhookPath,
     abortSignal,
     isStopped,
-    mediaMaxMb,
     statusSink,
     fetcher,
   } = params;
   const pollTimeout = 30;
+  const processingContext = {
+    token,
+    account,
+    config,
+    runtime,
+    core,
+    mediaMaxMb,
+    canHostMedia,
+    webhookUrl,
+    webhookPath,
+    statusSink,
+    fetcher,
+  };
 
   runtime.log?.(`[${account.accountId}] Zalo polling loop started timeout=${String(pollTimeout)}s`);
 
-  const poll = async () => {
+  const poll = async (): Promise<void> => {
     if (isStopped() || abortSignal.aborted) {
-      return;
+      return undefined;
     }
 
     try {
       const response = await getUpdates(token, { timeout: pollTimeout }, fetcher);
+      if (isStopped() || abortSignal.aborted) {
+        return undefined;
+      }
       if (response.ok && response.result) {
         statusSink?.({ lastInboundAt: Date.now() });
-        await processUpdate(
-          response.result,
-          token,
-          account,
-          config,
-          runtime,
-          core,
-          mediaMaxMb,
-          statusSink,
-          fetcher,
-        );
+        await processUpdate({
+          update: response.result,
+          ...processingContext,
+        });
       }
     } catch (err) {
       if (err instanceof ZaloApiError && err.isPollingTimeout) {
@@ -215,38 +296,39 @@ function startPollingLoop(params: {
   void poll();
 }
 
-async function processUpdate(
-  update: ZaloUpdate,
-  token: string,
-  account: ResolvedZaloAccount,
-  config: OpenClawConfig,
-  runtime: ZaloRuntimeEnv,
-  core: ZaloCoreRuntime,
-  mediaMaxMb: number,
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void,
-  fetcher?: ZaloFetch,
-): Promise<void> {
+async function processUpdate(params: ZaloUpdateProcessingParams): Promise<void> {
+  const { update, token, account, config, runtime, core, mediaMaxMb, statusSink, fetcher } = params;
   const { event_name, message } = update;
+  const sharedContext = {
+    token,
+    account,
+    config,
+    runtime,
+    core,
+    mediaMaxMb,
+    canHostMedia: params.canHostMedia,
+    webhookUrl: params.webhookUrl,
+    webhookPath: params.webhookPath,
+    statusSink,
+    fetcher,
+  };
   if (!message) {
-    return;
+    return undefined;
   }
 
   switch (event_name) {
     case "message.text.received":
-      await handleTextMessage(message, token, account, config, runtime, core, statusSink, fetcher);
+      await handleTextMessage({
+        message,
+        ...sharedContext,
+      });
       break;
     case "message.image.received":
-      await handleImageMessage(
+      await handleImageMessage({
         message,
-        token,
-        account,
-        config,
-        runtime,
-        core,
+        ...sharedContext,
         mediaMaxMb,
-        statusSink,
-        fetcher,
-      );
+      });
       break;
     case "message.sticker.received":
       logVerbose(core, runtime, `[${account.accountId}] Received sticker from ${message.from.id}`);
@@ -262,55 +344,43 @@ async function processUpdate(
 }
 
 async function handleTextMessage(
-  message: ZaloMessage,
-  token: string,
-  account: ResolvedZaloAccount,
-  config: OpenClawConfig,
-  runtime: ZaloRuntimeEnv,
-  core: ZaloCoreRuntime,
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void,
-  fetcher?: ZaloFetch,
+  params: ZaloProcessingContext & { message: ZaloMessage },
 ): Promise<void> {
+  const { message } = params;
   const { text } = message;
   if (!text?.trim()) {
-    return;
+    return undefined;
   }
 
   await processMessageWithPipeline({
-    message,
-    token,
-    account,
-    config,
-    runtime,
-    core,
+    ...params,
     text,
     mediaPath: undefined,
     mediaType: undefined,
-    statusSink,
-    fetcher,
   });
 }
 
-async function handleImageMessage(
-  message: ZaloMessage,
-  token: string,
-  account: ResolvedZaloAccount,
-  config: OpenClawConfig,
-  runtime: ZaloRuntimeEnv,
-  core: ZaloCoreRuntime,
-  mediaMaxMb: number,
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void,
-  fetcher?: ZaloFetch,
-): Promise<void> {
-  const { photo, caption } = message;
+async function handleImageMessage(params: ZaloImageMessageParams): Promise<void> {
+  const { message, mediaMaxMb, account, core, runtime } = params;
+  const { photo_url, caption } = message;
+  const authorization = await authorizeZaloMessage({
+    ...params,
+    text: caption,
+    // Use a sentinel so auth sees this as an inbound image before the download happens.
+    mediaPath: photo_url ? "__pending_media__" : undefined,
+    mediaType: undefined,
+  });
+  if (!authorization) {
+    return;
+  }
 
   let mediaPath: string | undefined;
   let mediaType: string | undefined;
 
-  if (photo) {
+  if (photo_url) {
     try {
       const maxBytes = mediaMaxMb * 1024 * 1024;
-      const fetched = await core.channel.media.fetchRemoteMedia({ url: photo, maxBytes });
+      const fetched = await core.channel.media.fetchRemoteMedia({ url: photo_url, maxBytes });
       const saved = await core.channel.media.saveMediaBuffer(
         fetched.buffer,
         fetched.contentType,
@@ -325,57 +395,30 @@ async function handleImageMessage(
   }
 
   await processMessageWithPipeline({
-    message,
-    token,
-    account,
-    config,
-    runtime,
-    core,
+    ...params,
+    authorization,
     text: caption,
     mediaPath,
     mediaType,
-    statusSink,
-    fetcher,
   });
 }
 
-async function processMessageWithPipeline(params: {
-  message: ZaloMessage;
-  token: string;
-  account: ResolvedZaloAccount;
-  config: OpenClawConfig;
-  runtime: ZaloRuntimeEnv;
-  core: ZaloCoreRuntime;
-  text?: string;
-  mediaPath?: string;
-  mediaType?: string;
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
-  fetcher?: ZaloFetch;
-}): Promise<void> {
-  const {
-    message,
-    token,
-    account,
-    config,
-    runtime,
-    core,
-    text,
-    mediaPath,
-    mediaType,
-    statusSink,
-    fetcher,
-  } = params;
-  const pairing = createScopedPairingAccess({
+async function authorizeZaloMessage(
+  params: ZaloMessagePipelineParams,
+): Promise<ZaloMessageAuthorizationResult | undefined> {
+  const { message, account, config, runtime, core, text, mediaPath, token, statusSink, fetcher } =
+    params;
+  const pairing = createChannelPairingController({
     core,
     channel: "zalo",
     accountId: account.accountId,
   });
-  const { from, chat, message_id, date } = message;
+  const { from, chat } = message;
 
   const isGroup = chat.chat_type === "GROUP";
   const chatId = chat.id;
   const senderId = from.id;
-  const senderName = from.name;
+  const senderName = from.display_name ?? from.name;
 
   const dmPolicy = account.config.dmPolicy ?? "pairing";
   const configAllowFrom = (account.config.allowFrom ?? []).map((v) => String(v));
@@ -411,7 +454,7 @@ async function processMessageWithPipeline(params: {
       } else if (groupAccess.reason === "sender_not_allowlisted") {
         logVerbose(core, runtime, `zalo: drop group sender ${senderId} (groupPolicy=allowlist)`);
       }
-      return;
+      return undefined;
     }
   }
 
@@ -426,6 +469,8 @@ async function processMessageWithPipeline(params: {
       configuredGroupAllowFrom: groupAllowFrom,
       senderId,
       isSenderAllowed: isZaloSenderAllowed,
+      channel: "zalo",
+      accountId: account.accountId,
       readAllowFromStore: pairing.readAllowFromStore,
       runtime: core.channel.commands,
     });
@@ -437,16 +482,14 @@ async function processMessageWithPipeline(params: {
   });
   if (directDmOutcome === "disabled") {
     logVerbose(core, runtime, `Blocked zalo DM from ${senderId} (dmPolicy=disabled)`);
-    return;
+    return undefined;
   }
   if (directDmOutcome === "unauthorized") {
     if (dmPolicy === "pairing") {
-      await issuePairingChallenge({
-        channel: "zalo",
+      await pairing.issueChallenge({
         senderId,
         senderIdLine: `Your Zalo user id: ${senderId}`,
         meta: { name: senderName ?? undefined },
-        upsertPairingRequest: pairing.upsertPairingRequest,
         onCreated: () => {
           logVerbose(core, runtime, `zalo pairing request sender=${senderId}`);
         },
@@ -472,8 +515,45 @@ async function processMessageWithPipeline(params: {
         `Blocked unauthorized zalo sender ${senderId} (dmPolicy=${dmPolicy})`,
       );
     }
+    return undefined;
+  }
+
+  return {
+    chatId,
+    commandAuthorized,
+    isGroup,
+    rawBody,
+    senderId,
+    senderName,
+  };
+}
+
+async function processMessageWithPipeline(params: ZaloMessagePipelineParams): Promise<void> {
+  const {
+    message,
+    token,
+    account,
+    config,
+    runtime,
+    core,
+    mediaPath,
+    mediaType,
+    statusSink,
+    fetcher,
+    authorization: authorizationOverride,
+  } = params;
+  const { message_id, date } = message;
+  const authorization =
+    authorizationOverride ??
+    (await authorizeZaloMessage({
+      ...params,
+      mediaPath,
+      mediaType,
+    }));
+  if (!authorization) {
     return;
   }
+  const { isGroup, chatId, senderId, senderName, rawBody, commandAuthorized } = authorization;
 
   const { route, buildEnvelope } = resolveInboundRouteEnvelopeBuilderWithRuntime({
     cfg: config,
@@ -504,36 +584,54 @@ async function processMessageWithPipeline(params: {
     body: rawBody,
   });
 
-  const ctxPayload = core.channel.reply.finalizeInboundContext({
-    Body: body,
-    BodyForAgent: rawBody,
-    RawBody: rawBody,
-    CommandBody: rawBody,
-    From: isGroup ? `zalo:group:${chatId}` : `zalo:${senderId}`,
-    To: `zalo:${chatId}`,
-    SessionKey: route.sessionKey,
-    AccountId: route.accountId,
-    ChatType: isGroup ? "group" : "direct",
-    ConversationLabel: fromLabel,
-    SenderName: senderName || undefined,
-    SenderId: senderId,
-    CommandAuthorized: commandAuthorized,
-    Provider: "zalo",
-    Surface: "zalo",
-    MessageSid: message_id,
-    MediaPath: mediaPath,
-    MediaType: mediaType,
-    MediaUrl: mediaPath,
-    OriginatingChannel: "zalo",
-    OriginatingTo: `zalo:${chatId}`,
-  });
-
-  await core.channel.session.recordInboundSession({
-    storePath,
-    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
-    ctx: ctxPayload,
-    onRecordError: (err) => {
-      runtime.error?.(`zalo: failed updating session meta: ${String(err)}`);
+  const ctxPayload = core.channel.turn.buildContext({
+    channel: "zalo",
+    accountId: route.accountId,
+    messageId: message_id,
+    timestamp: date ? date * 1000 : undefined,
+    from: isGroup ? `zalo:group:${chatId}` : `zalo:${senderId}`,
+    sender: {
+      id: senderId,
+      name: senderName || undefined,
+    },
+    conversation: {
+      kind: isGroup ? "group" : "direct",
+      id: chatId,
+      label: fromLabel,
+      routePeer: {
+        kind: isGroup ? "group" : "direct",
+        id: chatId,
+      },
+    },
+    route: {
+      agentId: route.agentId,
+      accountId: route.accountId,
+      routeSessionKey: route.sessionKey,
+    },
+    reply: {
+      to: `zalo:${chatId}`,
+      originatingTo: `zalo:${chatId}`,
+    },
+    message: {
+      body,
+      bodyForAgent: rawBody,
+      rawBody,
+      commandBody: rawBody,
+      envelopeFrom: fromLabel,
+    },
+    media:
+      mediaPath || mediaType
+        ? [
+            {
+              path: mediaPath,
+              url: mediaPath,
+              contentType: mediaType,
+            },
+          ]
+        : undefined,
+    extra: {
+      CommandAuthorized: commandAuthorized,
+      GroupSubject: undefined,
     },
   });
 
@@ -542,61 +640,95 @@ async function processMessageWithPipeline(params: {
     channel: "zalo",
     accountId: account.accountId,
   });
-  const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({
+  const { onModelSelected, ...replyPipeline } = createChannelReplyPipeline({
     cfg: config,
     agentId: route.agentId,
     channel: "zalo",
     accountId: account.accountId,
-  });
-  const typingCallbacks = createTypingCallbacks({
-    start: async () => {
-      await sendChatAction(
-        token,
-        {
-          chat_id: chatId,
-          action: "typing",
-        },
-        fetcher,
-        ZALO_TYPING_TIMEOUT_MS,
-      );
-    },
-    onStartError: (err) => {
-      logTypingFailure({
-        log: (message) => logVerbose(core, runtime, message),
-        channel: "zalo",
-        action: "start",
-        target: chatId,
-        error: err,
-      });
-    },
-  });
-
-  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-    ctx: ctxPayload,
-    cfg: config,
-    dispatcherOptions: {
-      ...prefixOptions,
-      typingCallbacks,
-      deliver: async (payload) => {
-        await deliverZaloReply({
-          payload,
+    typing: {
+      start: async () => {
+        await sendChatAction(
           token,
-          chatId,
-          runtime,
-          core,
-          config,
-          accountId: account.accountId,
-          statusSink,
+          {
+            chat_id: chatId,
+            action: "typing",
+          },
           fetcher,
-          tableMode,
-        });
+          ZALO_TYPING_TIMEOUT_MS,
+        );
       },
-      onError: (err, info) => {
-        runtime.error?.(`[${account.accountId}] Zalo ${info.kind} reply failed: ${String(err)}`);
+      onStartError: (err) => {
+        logTypingFailure({
+          log: (message) => logVerbose(core, runtime, message),
+          channel: "zalo",
+          action: "start",
+          target: chatId,
+          error: err,
+        });
       },
     },
-    replyOptions: {
-      onModelSelected,
+  });
+
+  await core.channel.turn.run({
+    channel: "zalo",
+    accountId: account.accountId,
+    raw: message,
+    adapter: {
+      ingest: () => ({
+        id: message_id,
+        timestamp: date ? date * 1000 : undefined,
+        rawText: rawBody,
+        textForAgent: rawBody,
+        textForCommands: rawBody,
+        raw: message,
+      }),
+      resolveTurn: () => ({
+        cfg: config,
+        channel: "zalo",
+        accountId: account.accountId,
+        agentId: route.agentId,
+        routeSessionKey: route.sessionKey,
+        storePath,
+        ctxPayload,
+        recordInboundSession: core.channel.session.recordInboundSession,
+        dispatchReplyWithBufferedBlockDispatcher:
+          core.channel.reply.dispatchReplyWithBufferedBlockDispatcher,
+        delivery: {
+          deliver: async (payload) => {
+            await deliverZaloReply({
+              payload,
+              token,
+              chatId,
+              runtime,
+              core,
+              config,
+              webhookUrl: params.webhookUrl,
+              webhookPath: params.webhookPath,
+              proxyUrl: account.config.proxy,
+              mediaMaxBytes: params.mediaMaxMb * 1024 * 1024,
+              canHostMedia: params.canHostMedia,
+              accountId: account.accountId,
+              statusSink,
+              fetcher,
+              tableMode,
+            });
+          },
+          onError: (err, info) => {
+            runtime.error?.(
+              `[${account.accountId}] Zalo ${info.kind} reply failed: ${String(err)}`,
+            );
+          },
+        },
+        dispatcherOptions: replyPipeline,
+        replyOptions: {
+          onModelSelected,
+        },
+        record: {
+          onRecordError: (err) => {
+            runtime.error?.(`zalo: failed updating session meta: ${String(err)}`);
+          },
+        },
+      }),
     },
   });
 }
@@ -608,41 +740,70 @@ async function deliverZaloReply(params: {
   runtime: ZaloRuntimeEnv;
   core: ZaloCoreRuntime;
   config: OpenClawConfig;
+  webhookUrl?: string;
+  webhookPath?: string;
+  proxyUrl?: string;
+  mediaMaxBytes: number;
+  canHostMedia: boolean;
   accountId?: string;
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  statusSink?: ZaloStatusSink;
   fetcher?: ZaloFetch;
   tableMode?: MarkdownTableMode;
 }): Promise<void> {
-  const { payload, token, chatId, runtime, core, config, accountId, statusSink, fetcher } = params;
+  const {
+    payload,
+    token,
+    chatId,
+    runtime,
+    core,
+    config,
+    webhookUrl,
+    webhookPath,
+    proxyUrl,
+    mediaMaxBytes,
+    canHostMedia,
+    accountId,
+    statusSink,
+    fetcher,
+  } = params;
   const tableMode = params.tableMode ?? "code";
-  const text = core.channel.text.convertMarkdownTables(payload.text ?? "", tableMode);
-  const sentMedia = await sendMediaWithLeadingCaption({
-    mediaUrls: resolveOutboundMediaUrls(payload),
-    caption: text,
-    send: async ({ mediaUrl, caption }) => {
-      await sendPhoto(token, { chat_id: chatId, photo: mediaUrl, caption }, fetcher);
-      statusSink?.({ lastOutboundAt: Date.now() });
-    },
-    onError: (error) => {
-      runtime.error?.(`Zalo photo send failed: ${String(error)}`);
-    },
+  const reply = resolveSendableOutboundReplyParts(payload, {
+    text: core.channel.text.convertMarkdownTables(payload.text ?? "", tableMode),
   });
-  if (sentMedia) {
-    return;
-  }
-
-  if (text) {
-    const chunkMode = core.channel.text.resolveChunkMode(config, "zalo", accountId);
-    const chunks = core.channel.text.chunkMarkdownTextWithMode(text, ZALO_TEXT_LIMIT, chunkMode);
-    for (const chunk of chunks) {
+  const chunkMode = core.channel.text.resolveChunkMode(config, "zalo", accountId);
+  await deliverTextOrMediaReply({
+    payload,
+    text: reply.text,
+    chunkText: (value) =>
+      core.channel.text.chunkMarkdownTextWithMode(value, ZALO_TEXT_LIMIT, chunkMode),
+    sendText: async (chunk) => {
       try {
         await sendMessage(token, { chat_id: chatId, text: chunk }, fetcher);
         statusSink?.({ lastOutboundAt: Date.now() });
       } catch (err) {
         runtime.error?.(`Zalo message send failed: ${String(err)}`);
       }
-    }
-  }
+    },
+    sendMedia: async ({ mediaUrl, caption }) => {
+      const sendableMediaUrl =
+        canHostMedia && webhookUrl && webhookPath
+          ? await prepareHostedZaloMediaUrl({
+              mediaUrl,
+              webhookUrl,
+              webhookPath,
+              maxBytes: mediaMaxBytes,
+              proxyUrl,
+            })
+          : mediaUrl;
+      await sendPhoto(token, { chat_id: chatId, photo: sendableMediaUrl, caption }, fetcher);
+      statusSink?.({ lastOutboundAt: Date.now() });
+    },
+    onMediaError: (error) => {
+      runtime.error?.(
+        `Zalo photo send failed: ${error instanceof Error ? error.message : JSON.stringify(error)}`,
+      );
+    },
+  });
 }
 
 export async function monitorZaloProvider(options: ZaloMonitorOptions): Promise<void> {
@@ -664,6 +825,23 @@ export async function monitorZaloProvider(options: ZaloMonitorOptions): Promise<
   const effectiveMediaMaxMb = account.config.mediaMaxMb ?? DEFAULT_MEDIA_MAX_MB;
   const fetcher = fetcherOverride ?? resolveZaloProxyFetch(account.config.proxy);
   const mode = useWebhook ? "webhook" : "polling";
+  const effectiveWebhookUrl = normalizeWebhookUrl(webhookUrl ?? account.config.webhookUrl);
+  const effectiveWebhookPath =
+    effectiveWebhookUrl || webhookPath?.trim() || account.config.webhookPath?.trim()
+      ? (resolveWebhookPath({
+          webhookPath: webhookPath ?? account.config.webhookPath,
+          webhookUrl: effectiveWebhookUrl,
+          defaultPath: null,
+        }) ?? undefined)
+      : undefined;
+  const canHostMedia = Boolean(effectiveWebhookUrl && effectiveWebhookPath);
+  const hostedMediaRoutePath =
+    canHostMedia && effectiveWebhookUrl
+      ? resolveHostedZaloMediaRoutePrefix({
+          webhookUrl: effectiveWebhookUrl,
+          webhookPath: effectiveWebhookPath,
+        })
+      : undefined;
 
   let stopped = false;
   const stopHandlers: Array<() => void> = [];
@@ -678,32 +856,49 @@ export async function monitorZaloProvider(options: ZaloMonitorOptions): Promise<
       handler();
     }
   };
+  const stopOnAbort = () => {
+    if (!useWebhook) {
+      stop();
+    }
+  };
+
+  abortSignal.addEventListener("abort", stopOnAbort, { once: true });
 
   runtime.log?.(
     `[${account.accountId}] Zalo provider init mode=${mode} mediaMaxMb=${String(effectiveMediaMaxMb)}`,
   );
 
   try {
+    if (hostedMediaRoutePath) {
+      const unregisterHostedMediaRoute = registerSharedHostedMediaRoute({
+        path: hostedMediaRoutePath,
+        accountId: account.accountId,
+        log: runtime.log,
+      });
+      stopHandlers.push(unregisterHostedMediaRoute);
+    }
+
     if (useWebhook) {
-      if (!webhookUrl || !webhookSecret) {
+      const { registerZaloWebhookTarget } = await loadZaloWebhookModule();
+      if (!effectiveWebhookUrl || !webhookSecret) {
         throw new Error("Zalo webhookUrl and webhookSecret are required for webhook mode");
       }
-      if (!webhookUrl.startsWith("https://")) {
+      if (!effectiveWebhookUrl.startsWith("https://")) {
         throw new Error("Zalo webhook URL must use HTTPS");
       }
       if (webhookSecret.length < 8 || webhookSecret.length > 256) {
         throw new Error("Zalo webhook secret must be 8-256 characters");
       }
 
-      const path = resolveWebhookPath({ webhookPath, webhookUrl, defaultPath: null });
+      const path = effectiveWebhookPath;
       if (!path) {
         throw new Error("Zalo webhookPath could not be derived");
       }
 
       runtime.log?.(
-        `[${account.accountId}] Zalo configuring webhook path=${path} target=${describeWebhookTarget(webhookUrl)}`,
+        `[${account.accountId}] Zalo configuring webhook path=${path} target=${describeWebhookTarget(effectiveWebhookUrl)}`,
       );
-      await setWebhook(token, { url: webhookUrl, secret_token: webhookSecret }, fetcher);
+      await setWebhook(token, { url: effectiveWebhookUrl, secret_token: webhookSecret }, fetcher);
       let webhookCleanupPromise: Promise<void> | undefined;
       cleanupWebhook = async () => {
         if (!webhookCleanupPromise) {
@@ -725,18 +920,41 @@ export async function monitorZaloProvider(options: ZaloMonitorOptions): Promise<
       };
       runtime.log?.(`[${account.accountId}] Zalo webhook registered path=${path}`);
 
-      const unregister = registerZaloWebhookTarget({
-        token,
-        account,
-        config,
-        runtime,
-        core,
-        path,
-        secret: webhookSecret,
-        statusSink: (patch) => statusSink?.(patch),
-        mediaMaxMb: effectiveMediaMaxMb,
-        fetcher,
-      });
+      const unregister = registerZaloWebhookTarget(
+        {
+          token,
+          account,
+          config,
+          runtime,
+          core,
+          path,
+          webhookUrl: effectiveWebhookUrl,
+          webhookPath: path,
+          secret: webhookSecret,
+          statusSink: (patch) => statusSink?.(patch),
+          mediaMaxMb: effectiveMediaMaxMb,
+          canHostMedia,
+          fetcher,
+        },
+        {
+          route: {
+            auth: "plugin",
+            match: "exact",
+            pluginId: "zalo",
+            source: "zalo-webhook",
+            accountId: account.accountId,
+            log: 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");
+              }
+            },
+          },
+        },
+      );
       stopHandlers.push(unregister);
       await waitForAbortSignal(abortSignal);
       return;
@@ -779,6 +997,9 @@ export async function monitorZaloProvider(options: ZaloMonitorOptions): Promise<
       config,
       runtime,
       core,
+      canHostMedia,
+      webhookUrl: effectiveWebhookUrl,
+      webhookPath: effectiveWebhookPath,
       abortSignal,
       isStopped: () => stopped,
       mediaMaxMb: effectiveMediaMaxMb,
@@ -793,6 +1014,7 @@ export async function monitorZaloProvider(options: ZaloMonitorOptions): Promise<
     );
     throw err;
   } finally {
+    abortSignal.removeEventListener("abort", stopOnAbort);
     await cleanupWebhook?.();
     stop();
     runtime.log?.(`[${account.accountId}] Zalo provider stopped mode=${mode}`);
@@ -802,4 +1024,5 @@ export async function monitorZaloProvider(options: ZaloMonitorOptions): Promise<
 export const __testing = {
   evaluateZaloGroupAccess,
   resolveZaloRuntimeGroupPolicy,
+  clearHostedMediaRouteRefsForTest: () => hostedMediaRouteRefs.clear(),
 };