@soimy/dingtalk 3.5.2 → 3.5.3

package/src/reply-strategy-card.ts

@@ -9,8 +9,14 @@
 import {
   finishAICard,
   isCardInTerminalState,
+  recallAICardMessage,
 } from "./card-service";
+import { splitCardReasoningAnswerText } from "./card/reasoning-answer-split";
 import { createReasoningBlockAssembler } from "./card/reasoning-block-assembler";
+import {
+  resolveCardStreamingMode,
+  shouldWarnDeprecatedCardRealTimeStreamOnce,
+} from "./card/card-streaming-mode";
 import { createCardDraftController } from "./card-draft-controller";
 import { attachCardRunController } from "./card/card-run-registry";
 import type { DeliverPayload, ReplyOptions, ReplyStrategy, ReplyStrategyContext } from "./reply-strategy";
@@ -20,19 +26,43 @@ import { AICardStatus } from "./types";
 import { formatDingTalkErrorPayloadLog } from "./utils";
 
 const EMPTY_FINAL_REPLY = "✅ Done";
+type CardReplyLifecycleState = "open" | "final_seen" | "sealed";
 
 export function createCardReplyStrategy(
   ctx: ReplyStrategyContext & { card: AICardInstance; isStopRequested?: () => boolean },
 ): ReplyStrategy {
   const { card, config, log, isStopRequested } = ctx;
+  const { mode, usedDeprecatedCardRealTimeStream } = resolveCardStreamingMode(config);
+  const streamAnswerLive = mode === "answer" || mode === "all";
+  const streamThinkingLive = mode === "all";
+  let lifecycleState: CardReplyLifecycleState = "open";
+  const shouldAcceptAnswerSnapshot = () => lifecycleState === "open";
+  const isLifecycleSealed = () => lifecycleState === "sealed";
+
+  if (usedDeprecatedCardRealTimeStream) {
+    const warningKey = `dingtalk-card-streaming:${ctx.accountId || config.clientId || "default"}`;
+    if (shouldWarnDeprecatedCardRealTimeStreamOnce(warningKey)) {
+      log?.warn?.(
+        "[DingTalk][Config] `cardRealTimeStream` is deprecated. Use `cardStreamingMode` with `off` | `answer` | `all`.",
+      );
+    }
+  }
 
-  const controller = createCardDraftController({ card, log });
+  const controller = createCardDraftController({
+    card,
+    log,
+    throttleMs: config.cardStreamInterval ?? 1000,
+  });
   const reasoningAssembler = createReasoningBlockAssembler();
   if (card.outTrackId) {
     attachCardRunController(card.outTrackId, controller);
   }
   let finalTextForFallback: string | undefined;
   let sawFinalDelivery = false;
+  let successfulMediaDeliveries = 0;
+  let failedMediaDeliveries = 0;
+  /** Tracks the latest reasoning snapshot text for non-streaming boundary flush. */
+  let latestReasoningSnapshot = "";
 
   const getRenderedTimeline = (options: { preferFinalAnswer?: boolean } = {}): string => {
     const fallbackAnswer = finalTextForFallback || (sawFinalDelivery ? EMPTY_FINAL_REPLY : undefined);
@@ -42,6 +72,12 @@ export function createCardReplyStrategy(
     });
   };
 
+  const getRawRenderedTimeline = (): string =>
+    controller.getRenderedContent({
+      fallbackAnswer: undefined,
+      overrideAnswer: undefined,
+    });
+
   const appendAssembledThinkingBlocks = async (blocks: string[]): Promise<void> => {
     for (const block of blocks) {
       if (!block.trim() || isStopRequested?.()) {
@@ -51,25 +87,157 @@ export function createCardReplyStrategy(
     }
   };
 
-  const ingestReasoningSnapshot = async (text: string | undefined): Promise<void> => {
+  const applyModeAwareDeliveredReasoning = async (text: string | undefined): Promise<void> => {
+    if (typeof text !== "string" || !text.trim() || isStopRequested?.()) {
+      return;
+    }
+    if (streamThinkingLive) {
+      await controller.appendThinkingBlock(text);
+      return;
+    }
+    await applyModeAwareReasoningSnapshot(text);
+  };
+
+  const applyModeAwareReasoningSnapshot = async (text: string | undefined): Promise<void> => {
+    if (typeof text !== "string" || !text.trim() || isStopRequested?.()) {
+      return;
+    }
+    if (streamThinkingLive) {
+      latestReasoningSnapshot = text;
+      await controller.updateReasoning(text);
+      return;
+    }
     const blocks = reasoningAssembler.ingestSnapshot(text);
+    const trimmed = text.trimStart();
     if (
       blocks.length === 0
-      && typeof text === "string"
-      && text.trim()
-      && !text.trimStart().startsWith("Reasoning:")
+      && !trimmed.startsWith("Reasoning:")
     ) {
-      await appendAssembledThinkingBlocks([text.trim()]);
+      if (trimmed.startsWith("Reason:")) {
+        latestReasoningSnapshot = "";
+        return;
+      }
+      latestReasoningSnapshot = text.trim();
       return;
     }
+    latestReasoningSnapshot = "";
     await appendAssembledThinkingBlocks(blocks);
   };
 
   const flushPendingReasoning = async (): Promise<void> => {
+    if (streamThinkingLive) {
+      await controller.sealActiveThinking();
+      latestReasoningSnapshot = "";
+      return;
+    }
     const blocks = reasoningAssembler.flushPendingAtBoundary();
+    if (latestReasoningSnapshot) {
+      blocks.push(latestReasoningSnapshot);
+      latestReasoningSnapshot = "";
+    }
     await appendAssembledThinkingBlocks(blocks);
   };
 
+  const handleAssistantBoundary = async (): Promise<void> => {
+    if (streamThinkingLive) {
+      await controller.sealActiveThinking();
+      latestReasoningSnapshot = "";
+      reasoningAssembler.reset();
+      await controller.notifyNewAssistantTurn();
+      return;
+    }
+    const pendingReasoningBlocks = reasoningAssembler.flushPendingAtBoundary();
+    if (latestReasoningSnapshot) {
+      pendingReasoningBlocks.push(latestReasoningSnapshot);
+      latestReasoningSnapshot = "";
+    }
+    reasoningAssembler.reset();
+    const turnBoundary = controller.notifyNewAssistantTurn();
+    if (pendingReasoningBlocks.length > 0) {
+      await turnBoundary;
+      await appendAssembledThinkingBlocks(pendingReasoningBlocks);
+      return;
+    }
+    await turnBoundary;
+  };
+
+  const normalizeDeliveredText = (
+    text: string,
+    options: { isReasoning: boolean },
+  ): { reasoningText?: string; answerText?: string } => {
+    if (options.isReasoning) {
+      const split = splitCardReasoningAnswerText(text);
+      return { reasoningText: split.reasoningText || text };
+    }
+    const split = splitCardReasoningAnswerText(text);
+    return {
+      reasoningText: split.reasoningText,
+      answerText: split.answerText,
+    };
+  };
+
+  const applyDeliveredContent = async (
+    normalized: { reasoningText?: string; answerText?: string },
+    options: {
+      routeReasoningThroughModePolicy: boolean;
+      answerHandling?: "update" | "capture" | "ignore";
+    },
+  ): Promise<void> => {
+    if (normalized.reasoningText) {
+      if (options.routeReasoningThroughModePolicy) {
+        await applyModeAwareDeliveredReasoning(normalized.reasoningText);
+      } else {
+        // Conservative local split fallback: keep existing behavior for mixed payloads.
+        await controller.appendThinkingBlock(normalized.reasoningText);
+      }
+    }
+    if (normalized.answerText && options.answerHandling !== "ignore") {
+      if (options.answerHandling === "capture") {
+        finalTextForFallback = normalized.answerText;
+        return;
+      }
+      await controller.updateAnswer(normalized.answerText);
+    }
+  };
+
+  const handleAnswerSnapshot = async (text: string | undefined): Promise<void> => {
+    if (!shouldAcceptAnswerSnapshot() || isStopRequested?.()) {
+      return;
+    }
+    if (!text) {
+      return;
+    }
+    await controller.updateAnswer(text, { stream: streamAnswerLive });
+  };
+
+  const applySplitTextToTimeline = async (
+    text: string,
+    options: { answerHandling?: "update" | "capture" | "ignore" } = {},
+  ) => {
+    const normalized = normalizeDeliveredText(text, { isReasoning: false });
+    await applyDeliveredContent(normalized, {
+      routeReasoningThroughModePolicy: true,
+      answerHandling: options.answerHandling ?? "update",
+    });
+    return normalized;
+  };
+
+  const deliverMediaWithTracking = async (
+    mediaUrls: string[],
+    options: { audioAsVoice?: boolean },
+  ): Promise<void> => {
+    if (mediaUrls.length === 0) {
+      return;
+    }
+    try {
+      await ctx.deliverMedia(mediaUrls, options);
+      successfulMediaDeliveries += mediaUrls.length;
+    } catch (err) {
+      failedMediaDeliveries += mediaUrls.length;
+      throw err;
+    }
+  };
+
   return {
     getReplyOptions(): ReplyOptions {
       return {
@@ -78,37 +246,29 @@ export function createCardReplyStrategy(
         disableBlockStreaming: ctx.disableBlockStreaming ?? true,
 
         onAssistantMessageStart: async () => {
-          if (isStopRequested?.()) {
+          if (isLifecycleSealed() || isStopRequested?.()) {
             return;
           }
-          const pendingReasoningBlocks = reasoningAssembler.flushPendingAtBoundary();
-          reasoningAssembler.reset();
-          const turnBoundary = controller.notifyNewAssistantTurn();
-          if (pendingReasoningBlocks.length > 0) {
-            await turnBoundary;
-            await appendAssembledThinkingBlocks(pendingReasoningBlocks);
-            return;
-          }
-          await turnBoundary;
+          await handleAssistantBoundary();
         },
 
-        onPartialReply: config.cardRealTimeStream
-          ? async (payload) => {
-              if (payload.text && !isStopRequested?.()) {
-                await controller.updateAnswer(payload.text);
-              }
-            }
-          : undefined,
+        onPartialReply: async (payload) => {
+          await handleAnswerSnapshot(payload.text);
+        },
 
         onReasoningStream: async (payload) => {
-          if (payload.text && !isStopRequested?.()) {
-            await ingestReasoningSnapshot(payload.text);
+          if (isLifecycleSealed() || isStopRequested?.()) {
+            return;
           }
+          await applyModeAwareReasoningSnapshot(payload.text);
         },
       };
     },
 
     async deliver(payload: DeliverPayload): Promise<void> {
+      if (isLifecycleSealed()) {
+        return;
+      }
       const textToSend = payload.text;
 
       // Empty-payload guard — card final is an exception (e.g. file-only response).
@@ -120,8 +280,12 @@ export function createCardReplyStrategy(
 
       // ---- final: defer to finalize, just save text ----
       if (payload.kind === "final") {
+        const isFirstFinalDelivery = !sawFinalDelivery;
+        lifecycleState = "final_seen";
         await flushPendingReasoning();
-        sawFinalDelivery = true;
+        if (isFirstFinalDelivery) {
+          sawFinalDelivery = true;
+        }
         log?.info?.(
           `[DingTalk][Finalize] deliver(final) received — cardState=${card.state} ` +
           `textLen=${typeof textToSend === "string" ? textToSend.length : "null"} ` +
@@ -130,11 +294,22 @@ export function createCardReplyStrategy(
           `lastContent="${(controller.getLastContent() ?? "").slice(0, 80)}"`,
         );
         if (payload.mediaUrls.length > 0) {
-          await ctx.deliverMedia(payload.mediaUrls);
+          await deliverMediaWithTracking(payload.mediaUrls, { audioAsVoice: payload.audioAsVoice });
         }
         const rawFinalText = typeof textToSend === "string" ? textToSend : "";
         if (rawFinalText) {
-          finalTextForFallback = rawFinalText;
+          if (payload.isReasoning === true) {
+            await applyModeAwareReasoningSnapshot(rawFinalText);
+            await flushPendingReasoning();
+          } else {
+            const normalizedFinal = await applySplitTextToTimeline(rawFinalText, {
+              answerHandling: "capture",
+            });
+            if (isFirstFinalDelivery && !normalizedFinal.answerText && !normalizedFinal.reasoningText) {
+              finalTextForFallback = rawFinalText;
+            }
+            await flushPendingReasoning();
+          }
         }
         return;
       }
@@ -149,22 +324,32 @@ export function createCardReplyStrategy(
         log?.info?.(
           `[DingTalk] Tool result received, streaming to AI Card: ${(textToSend ?? "").slice(0, 100)}`,
         );
-        await controller.appendTool(textToSend ?? "");
+        if (lifecycleState === "final_seen") {
+          await controller.appendToolBeforeCurrentAnswer(textToSend ?? "");
+        } else {
+          await controller.appendTool(textToSend ?? "");
+        }
         return;
       }
 
       const isReasoningBlock = payload.isReasoning === true;
       if (typeof textToSend === "string" && textToSend.trim()) {
         if (isReasoningBlock) {
-          await ingestReasoningSnapshot(textToSend);
+          const normalized = normalizeDeliveredText(textToSend, { isReasoning: true });
+          await applyDeliveredContent(normalized, {
+            routeReasoningThroughModePolicy: true,
+            answerHandling: "ignore",
+          });
         } else {
-          await controller.updateAnswer(textToSend);
+          await applySplitTextToTimeline(textToSend, {
+            answerHandling: lifecycleState === "open" ? "update" : "capture",
+          });
         }
       }
 
       // ---- block: only handle reasoning/media (other text blocks are unused) ----
       if (payload.mediaUrls.length > 0) {
-        await ctx.deliverMedia(payload.mediaUrls);
+        await deliverMediaWithTracking(payload.mediaUrls, { audioAsVoice: payload.audioAsVoice });
       }
     },
 
@@ -180,16 +365,19 @@ export function createCardReplyStrategy(
 
       if (isStopRequested?.()) {
         log?.info?.("[DingTalk][Finalize] Skipping — card stop was requested");
+        lifecycleState = "sealed";
         return;
       }
 
       if (card.state === AICardStatus.FINISHED) {
         log?.info?.("[DingTalk][Finalize] Skipping — card already FINISHED");
+        lifecycleState = "sealed";
         return;
       }
 
       if (card.state === AICardStatus.STOPPED) {
         log?.info?.("[DingTalk][Finalize] Skipping — card already STOPPED");
+        lifecycleState = "sealed";
         return;
       }
 
@@ -217,6 +405,7 @@ export function createCardReplyStrategy(
         } else {
           log?.debug?.("[DingTalk] Card failed but no content to fallback with");
         }
+        lifecycleState = "sealed";
         return;
       }
 
@@ -226,6 +415,28 @@ export function createCardReplyStrategy(
         await controller.flush();
         await controller.waitForInFlight();
         const renderedTimeline = getRenderedTimeline({ preferFinalAnswer: true });
+        const rawRenderedTimeline = getRawRenderedTimeline();
+        const hasRenderedCardContent = Boolean(rawRenderedTimeline.trim());
+        const hasMeaningfulCardContent = hasRenderedCardContent
+          || Boolean((finalTextForFallback || "").trim())
+          || Boolean((controller.getFinalAnswerContent() || "").trim())
+          || Boolean((controller.getLastAnswerContent() || "").trim())
+          || Boolean((controller.getLastContent() || "").trim());
+        const shouldRecallEmptyCard =
+          successfulMediaDeliveries > 0
+          && failedMediaDeliveries === 0
+          && !hasMeaningfulCardContent;
+        if (shouldRecallEmptyCard) {
+          controller.stop();
+          log?.info?.(
+            `[DingTalk][Finalize] Attempting to recall empty card after successful media delivery ` +
+            `mediaCount=${successfulMediaDeliveries} conversationId=${card.conversationId}`,
+          );
+          if (await recallAICardMessage(card, log)) {
+            lifecycleState = "sealed";
+            return;
+          }
+        }
         const finalText = renderedTimeline || EMPTY_FINAL_REPLY;
         controller.stop();
         log?.info?.(
@@ -236,6 +447,7 @@ export function createCardReplyStrategy(
         await finishAICard(card, finalText, log, {
           quotedRef: ctx.replyQuotedRef,
         });
+        lifecycleState = "sealed";
 
         // In group chats, send a lightweight @mention via session webhook
         // so the sender gets a notification — card API doesn't support @mention.
@@ -261,10 +473,13 @@ export function createCardReplyStrategy(
           card.state = AICardStatus.FAILED;
           card.lastUpdated = Date.now();
         }
+      } finally {
+        lifecycleState = "sealed";
       }
     },
 
     async abort(_error: Error): Promise<void> {
+      lifecycleState = "sealed";
       if (!isCardInTerminalState(card.state)) {
         controller.stop();
         await controller.waitForInFlight();

package/src/reply-strategy-markdown.ts

@@ -119,7 +119,7 @@ export function createMarkdownReplyStrategy(
 
     async deliver(payload: DeliverPayload): Promise<void> {
       if (payload.mediaUrls.length > 0) {
-        await ctx.deliverMedia(payload.mediaUrls);
+        await ctx.deliverMedia(payload.mediaUrls, { audioAsVoice: payload.audioAsVoice });
         sentVisibleContent = true;
       }
 

package/src/reply-strategy.ts

@@ -12,9 +12,20 @@ import { createMarkdownReplyStrategy } from "./reply-strategy-markdown";
 
 // ---- Public types ------------------------------------------------
 
+type InternalReplyStrategyConfig = DingTalkConfig & {
+  /** @deprecated Internal compatibility only. Removed from public config surface. */
+  cardStreamReasoning?: boolean;
+};
+
 export interface DeliverPayload {
   text?: string;
   mediaUrls: string[];
+  /**
+   * Shared reply-runtime voice hint. Strategies forward this unchanged into the
+   * channel media delivery helper; inbound-handler is responsible for bridging
+   * legacy aliases (for example `asVoice`) into this single field.
+   */
+  audioAsVoice?: boolean;
   kind: "block" | "final" | "tool";
   isReasoning?: boolean;
 }
@@ -45,7 +56,7 @@ export interface ReplyStrategy {
 
 /** Shared context passed to every strategy implementation. */
 export interface ReplyStrategyContext {
-  config: DingTalkConfig;
+  config: InternalReplyStrategyConfig;
   to: string;
   sessionWebhook: string;
   senderId: string;
@@ -58,7 +69,12 @@ export interface ReplyStrategyContext {
   groupId?: string;
   log?: Logger;
   replyQuotedRef?: QuotedRef;
-  deliverMedia: (urls: string[]) => Promise<void>;
+  /**
+   * Channel-level media delivery hook. The `audioAsVoice` option is the same
+   * shared voice semantic carried on DeliverPayload, not a second independent
+   * config knob.
+   */
+  deliverMedia: (urls: string[], options?: { audioAsVoice?: boolean }) => Promise<void>;
   isStopRequested?: () => boolean;
 }
 

package/src/send-service.ts

@@ -212,6 +212,14 @@ function extractErrorCodeFromResponseData(data: unknown): string | null {
   }
 
   const payload = data as Record<string, unknown>;
+  const errcode = payload.errcode;
+  if (typeof errcode === "number" && Number.isFinite(errcode)) {
+    return String(errcode);
+  }
+  if (typeof errcode === "string" && errcode.trim()) {
+    return errcode.trim();
+  }
+
   const code = payload.code;
   if (typeof code === "string" && code.trim()) {
     return code.trim();
@@ -225,6 +233,62 @@ function extractErrorCodeFromResponseData(data: unknown): string | null {
   return null;
 }
 
+function summarizeSessionWebhookResponse(data: unknown): string {
+  if (!data || typeof data !== "object") {
+    return `type=${typeof data}`;
+  }
+  const payload = data as Record<string, unknown>;
+  const code = extractErrorCodeFromResponseData(payload) || "(none)";
+  const message = firstTrimmedString(
+    payload.message,
+    payload.errmsg,
+    payload.msg,
+    payload.errorMessage,
+  ) || "(none)";
+  const success =
+    typeof payload.success === "boolean"
+      ? String(payload.success)
+      : typeof payload.result === "boolean"
+        ? String(payload.result)
+        : "(none)";
+  const delivery = extractOutboundDeliveryMetadata(payload);
+  return (
+    `success=${success} code=${code} message=${message} ` +
+    `messageId=${delivery.messageId || "(none)"} ` +
+    `processQueryKey=${delivery.processQueryKey || "(none)"} ` +
+    `outTrackId=${delivery.outTrackId || "(none)"}`
+  );
+}
+
+function ensureSessionWebhookBusinessSuccess(
+  data: unknown,
+  context: { msgtype: string },
+): void {
+  if (!data || typeof data !== "object") {
+    return;
+  }
+  const payload = data as Record<string, unknown>;
+  const code = extractErrorCodeFromResponseData(payload);
+  const message = firstTrimmedString(
+    payload.message,
+    payload.errmsg,
+    payload.msg,
+    payload.errorMessage,
+  ) || "unknown error";
+
+  const hasFailureSuccessFlag = payload.success === false || payload.result === false;
+  const hasFailureCode = typeof code === "string" && code !== "" && code !== "0";
+  if (!hasFailureSuccessFlag && !hasFailureCode) {
+    return;
+  }
+
+  const reason = [
+    code && code !== "0" ? `code=${code}` : "",
+    message !== "unknown error" ? `message=${message}` : "",
+  ].filter(Boolean).join(" ");
+  throw new Error(`Session webhook ${context.msgtype} send failed${reason ? `: ${reason}` : ""}`);
+}
+
 function isProactivePermissionOrScopeError(code: string | null): boolean {
   if (!code) {
     return false;
@@ -400,7 +464,7 @@ export async function sendProactiveMedia(
     if (!uploadResult) {
       return { ok: false, error: "Failed to upload media" };
     }
-    const { mediaId, buffer } = uploadResult;
+    const { mediaId, buffer, durationMs: uploadedDurationMs } = uploadResult;
 
     const token = await getAccessToken(config, log);
     const { targetId, isExplicitUser } = stripTargetPrefix(target);
@@ -421,7 +485,8 @@ export async function sendProactiveMedia(
       msgParam = JSON.stringify({ photoURL: mediaId });
     } else if (mediaType === "voice") {
       msgKey = "sampleAudio";
-      const durationMs = await getVoiceDurationMs(mediaPath, mediaType, log, { preReadBuffer: buffer });
+      const durationMs = uploadedDurationMs
+        ?? await getVoiceDurationMs(mediaPath, mediaType, log, { preReadBuffer: buffer });
       msgParam = JSON.stringify({ mediaId, duration: String(durationMs) });
     } else {
       // sampleVideo requires picMediaId; fallback to sampleFile for broader compatibility.
@@ -555,14 +620,18 @@ export async function sendBySession(
       mediaLocalRoots: options.mediaLocalRoots,
     });
     if (uploadResult) {
-      const { mediaId, buffer } = uploadResult;
+      const { mediaId, buffer, durationMs: uploadedDurationMs } = uploadResult;
       let body: any;
 
       if (options.mediaType === "image") {
         body = { msgtype: "image", image: { media_id: mediaId } };
       } else if (options.mediaType === "voice") {
-        const durationMs = await getVoiceDurationMs(options.mediaPath, options.mediaType, log, { preReadBuffer: buffer });
+        const durationMs = uploadedDurationMs
+          ?? await getVoiceDurationMs(options.mediaPath, options.mediaType, log, { preReadBuffer: buffer });
         body = { msgtype: "voice", voice: { media_id: mediaId, duration: String(durationMs) } };
+        log?.debug?.(
+          `[DingTalk] Sending session voice message mediaId=${mediaId} durationMs=${durationMs}`,
+        );
       } else if (options.mediaType === "video") {
         body = { msgtype: "video", video: { media_id: mediaId } };
       } else if (options.mediaType === "file") {
@@ -577,6 +646,17 @@ export async function sendBySession(
           headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
           ...getProxyBypassOption(config),
         });
+        log?.debug?.(
+          `[DingTalk] Session webhook response msgtype=${body.msgtype} ${summarizeSessionWebhookResponse(result.data)}`,
+        );
+        ensureSessionWebhookBusinessSuccess(result.data, { msgtype: body.msgtype });
+        const delivery = extractOutboundDeliveryMetadata(result.data);
+        if (!delivery.messageId && !delivery.processQueryKey && !delivery.outTrackId) {
+          log?.warn?.(
+            `[DingTalk] Session webhook ${body.msgtype} response missing delivery metadata; ` +
+            summarizeSessionWebhookResponse(result.data),
+          );
+        }
         return result.data;
       }
     } else {
@@ -624,6 +704,10 @@ export async function sendBySession(
       headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
       ...getProxyBypassOption(config),
     });
+    log?.debug?.(
+      `[DingTalk] Session webhook response msgtype=${body.msgtype} ${summarizeSessionWebhookResponse(result.data)}`,
+    );
+    ensureSessionWebhookBusinessSuccess(result.data, { msgtype: body.msgtype });
     lastResult = result.data;
   }
   return lastResult;
@@ -662,6 +746,28 @@ export async function sendMessage(
       }
     }
 
+    if (options.sessionWebhook && options.mediaPath && options.mediaType === "voice") {
+      log?.debug?.(
+        "[DingTalk] Session webhook does not support voice replies reliably; " +
+        "using proactive media API for this voice response",
+      );
+      const proactiveVoiceResult = await sendProactiveMedia(
+        config,
+        conversationId,
+        options.mediaPath,
+        options.mediaType,
+        options,
+      );
+      if (!proactiveVoiceResult.ok) {
+        return { ok: false, error: proactiveVoiceResult.error || "Voice reply send failed" };
+      }
+      return {
+        ok: true,
+        data: proactiveVoiceResult.data,
+        messageId: proactiveVoiceResult.messageId,
+      };
+    }
+
     if (options.sessionWebhook) {
       const data = await sendBySession(config, options.sessionWebhook, text, options);
       const delivery = extractOutboundDeliveryMetadata(data);