@dingxiang-me/openclaw-wechat 1.4.1 → 1.7.2

package/src/wecom/policy-resolvers.js

@@ -2,9 +2,12 @@ export function createWecomPolicyResolvers({
   getGatewayRuntime,
   normalizeAccountId,
   resolveWecomBotModeConfig,
+  resolveWecomBotModeAccountsConfig,
   resolveWecomProxyConfig,
   resolveWecomCommandPolicyConfig,
   resolveWecomAllowFromPolicyConfig,
+  resolveWecomDmPolicyConfig,
+  resolveWecomEventPolicyConfig,
   resolveWecomGroupChatConfig,
   resolveWecomDebounceConfig,
   resolveWecomStreamingConfig,
@@ -31,16 +34,59 @@ export function createWecomPolicyResolvers({
     };
   }
 
-  function resolveWecomBotConfig(api) {
-    return resolveWecomBotModeConfig(resolveWecomPolicyInputs(api));
+  function resolveWecomBotConfigs(api) {
+    const inputs = resolveWecomPolicyInputs(api);
+    if (typeof resolveWecomBotModeAccountsConfig === "function") {
+      return resolveWecomBotModeAccountsConfig(inputs);
+    }
+    return [resolveWecomBotModeConfig(inputs)];
+  }
+
+  function resolveWecomBotConfig(api, accountId = "default") {
+    const normalizedAccountId = normalizeAccountId(accountId ?? "default");
+    const configs = resolveWecomBotConfigs(api);
+    const matched = configs.find((item) => normalizeAccountId(item?.accountId ?? "default") === normalizedAccountId);
+    if (matched) return matched;
+    if (normalizedAccountId !== "default") {
+      const fallback = configs.find((item) => normalizeAccountId(item?.accountId ?? "default") === "default");
+      if (fallback) return fallback;
+    }
+    return configs[0] ?? resolveWecomBotModeConfig(resolveWecomPolicyInputs(api));
   }
 
-  function resolveWecomBotProxyConfig(api) {
+  function resolveWecomBotProxyConfig(api, accountId = "default") {
     const inputs = resolveWecomPolicyInputs(api);
+    const normalizedAccountId = normalizeAccountId(accountId ?? "default");
+    const channelConfig = inputs.channelConfig ?? {};
+    const accountConfig =
+      normalizedAccountId === "default"
+        ? channelConfig
+        : channelConfig?.accounts && typeof channelConfig.accounts === "object"
+          ? channelConfig.accounts[normalizedAccountId] ?? {}
+          : {};
+    const botConfig = accountConfig?.bot && typeof accountConfig.bot === "object" ? accountConfig.bot : {};
+    const envVars = inputs.envVars ?? {};
+    const processEnvVars = inputs.processEnv ?? process.env;
+    const scopedBotProxyKey =
+      normalizedAccountId === "default" ? null : `WECOM_${normalizedAccountId.toUpperCase()}_BOT_PROXY`;
+    const scopedBotProxy = String(
+      (scopedBotProxyKey ? envVars?.[scopedBotProxyKey] ?? processEnvVars?.[scopedBotProxyKey] : undefined) ??
+        envVars?.WECOM_BOT_PROXY ??
+        processEnvVars?.WECOM_BOT_PROXY ??
+        "",
+    ).trim();
+    const fromBotConfig = String(botConfig?.outboundProxy ?? botConfig?.proxyUrl ?? botConfig?.proxy ?? "").trim();
+    if (fromBotConfig) return fromBotConfig;
+    if (scopedBotProxy) return scopedBotProxy;
+
+    const proxyAccountConfig = {
+      ...(accountConfig && typeof accountConfig === "object" ? accountConfig : {}),
+      ...(botConfig && typeof botConfig === "object" ? botConfig : {}),
+    };
     return resolveWecomProxyConfig({
       ...inputs,
-      accountId: "bot",
-      accountConfig: {},
+      accountId: normalizedAccountId,
+      accountConfig: proxyAccountConfig,
     });
   }
 
@@ -57,6 +103,34 @@ export function createWecomPolicyResolvers({
     });
   }
 
+  function resolveWecomDmPolicy(api, accountId, accountConfig = {}) {
+    const inputs = resolveWecomPolicyInputs(api);
+    if (typeof resolveWecomDmPolicyConfig !== "function") {
+      return { mode: "open", allowFrom: [], rejectMessage: "当前私聊账号未授权，请联系管理员。", enabled: false };
+    }
+    return resolveWecomDmPolicyConfig({
+      ...inputs,
+      accountId: normalizeAccountId(accountId ?? "default"),
+      accountConfig: accountConfig ?? {},
+    });
+  }
+
+  function resolveWecomEventPolicy(api, accountId, accountConfig = {}) {
+    const inputs = resolveWecomPolicyInputs(api);
+    if (typeof resolveWecomEventPolicyConfig !== "function") {
+      return {
+        enabled: true,
+        enterAgentWelcomeEnabled: false,
+        enterAgentWelcomeText: "你好，我是 AI 助手，直接发消息即可开始对话。",
+      };
+    }
+    return resolveWecomEventPolicyConfig({
+      ...inputs,
+      accountId: normalizeAccountId(accountId ?? "default"),
+      accountConfig: accountConfig ?? {},
+    });
+  }
+
   function resolveWecomGroupChatPolicy(api) {
     return resolveWecomGroupChatConfig(resolveWecomPolicyInputs(api));
   }
@@ -91,10 +165,13 @@ export function createWecomPolicyResolvers({
 
   return {
     resolveWecomPolicyInputs,
+    resolveWecomBotConfigs,
     resolveWecomBotConfig,
     resolveWecomBotProxyConfig,
     resolveWecomCommandPolicy,
     resolveWecomAllowFromPolicy,
+    resolveWecomDmPolicy,
+    resolveWecomEventPolicy,
     resolveWecomGroupChatPolicy,
     resolveWecomTextDebouncePolicy,
     resolveWecomReplyStreamingPolicy,

package/src/wecom/register-runtime.js

@@ -1,3 +1,5 @@
+import { analyzeWecomAccountConflicts } from "./account-diagnostics.js";
+
 export function createWecomRegisterRuntime({
   setGatewayRuntime,
   syncWecomSessionQueuePolicy,
@@ -6,6 +8,8 @@ export function createWecomRegisterRuntime({
   resolveWecomObservabilityPolicy,
   resolveWecomDynamicAgentPolicy,
   resolveWecomBotConfig,
+  resolveWecomBotConfigs,
+  listEnabledWecomAccounts,
   getWecomConfig,
   wecomChannelPlugin,
   wecomRouteRegistrar,
@@ -31,6 +35,12 @@ export function createWecomRegisterRuntime({
   if (typeof resolveWecomBotConfig !== "function") {
     throw new Error("createWecomRegisterRuntime: resolveWecomBotConfig is required");
   }
+  if (resolveWecomBotConfigs != null && typeof resolveWecomBotConfigs !== "function") {
+    throw new Error("createWecomRegisterRuntime: resolveWecomBotConfigs must be a function");
+  }
+  if (listEnabledWecomAccounts != null && typeof listEnabledWecomAccounts !== "function") {
+    throw new Error("createWecomRegisterRuntime: listEnabledWecomAccounts must be a function");
+  }
   if (typeof getWecomConfig !== "function") {
     throw new Error("createWecomRegisterRuntime: getWecomConfig is required");
   }
@@ -50,14 +60,22 @@ export function createWecomRegisterRuntime({
     const dynamicAgentPolicy = resolveWecomDynamicAgentPolicy(api);
 
     const botModeConfig = resolveWecomBotConfig(api);
+    const botModeConfigs =
+      typeof resolveWecomBotConfigs === "function"
+        ? resolveWecomBotConfigs(api)
+        : [botModeConfig];
+    const enabledBotConfigs = (Array.isArray(botModeConfigs) ? botModeConfigs : []).filter((item) => item?.enabled === true);
     const cfg = getWecomConfig(api);
     if (cfg) {
       api.logger.info?.(
         `wecom: config loaded (corpId=${cfg.corpId?.slice(0, 8)}..., proxy=${cfg.outboundProxy ? "on" : "off"})`,
       );
-    } else if (botModeConfig.enabled) {
+    } else if (enabledBotConfigs.length > 0) {
+      const webhookSummary = Array.from(
+        new Set(enabledBotConfigs.map((item) => String(item?.webhookPath || "/wecom/bot/callback"))),
+      ).join(", ");
       api.logger.info?.(
-        `wecom(bot): config loaded (webhook=${botModeConfig.webhookPath}, streamExpireMs=${botModeConfig.streamExpireMs})`,
+        `wecom(bot): config loaded (accounts=${enabledBotConfigs.length}, webhook=${webhookSummary}, streamExpireMs=${botModeConfig.streamExpireMs})`,
       );
     } else {
       api.logger.warn?.("wecom: no configuration found (check channels.wecom in openclaw.json)");
@@ -83,6 +101,17 @@ export function createWecomRegisterRuntime({
         `wecom: dynamic-agent on (mode=${dynamicAgentPolicy.mode}, userMap=${Object.keys(dynamicAgentPolicy.userMap || {}).length}, groupMap=${Object.keys(dynamicAgentPolicy.groupMap || {}).length}, mentionMap=${Object.keys(dynamicAgentPolicy.mentionMap || {}).length})`,
       );
     }
+    if (typeof listEnabledWecomAccounts === "function") {
+      const accountDiagnostics = analyzeWecomAccountConflicts({
+        accounts: listEnabledWecomAccounts(api),
+        botConfigs: enabledBotConfigs,
+      });
+      for (const issue of accountDiagnostics.issues) {
+        const line = `wecom: account diagnosis ${issue.code} ${issue.message}`;
+        if (issue.severity === "warn") api.logger.warn?.(line);
+        else api.logger.info?.(line);
+      }
+    }
 
     api.registerChannel({ plugin: wecomChannelPlugin });
     const botRouteRegistered = wecomRouteRegistrar.registerWecomBotWebhookRoute(api);

package/src/wecom/route-registration.js

@@ -1,5 +1,13 @@
+import {
+  buildDefaultAgentWebhookPath,
+  buildDefaultBotWebhookPath,
+  buildLegacyAgentWebhookPath,
+  buildLegacyBotWebhookPath,
+} from "./account-paths.js";
+
 export function createWecomRouteRegistrar({
   resolveWecomBotConfig,
+  resolveWecomBotConfigs,
   normalizePluginHttpPath,
   ensureBotStreamCleanupTimer,
   cleanupExpiredBotStreams,
@@ -29,8 +37,13 @@ export function createWecomRouteRegistrar({
   deliverBotReplyText,
   finishBotStream,
   groupAccountsByWebhookPath,
+  recordInboundMetric = () => {},
+  recordRuntimeErrorMetric = () => {},
 } = {}) {
   if (typeof resolveWecomBotConfig !== "function") throw new Error("createWecomRouteRegistrar: resolveWecomBotConfig is required");
+  if (typeof resolveWecomBotConfigs !== "function") {
+    throw new Error("createWecomRouteRegistrar: resolveWecomBotConfigs is required");
+  }
   if (typeof normalizePluginHttpPath !== "function") {
     throw new Error("createWecomRouteRegistrar: normalizePluginHttpPath is required");
   }
@@ -51,56 +64,173 @@ export function createWecomRouteRegistrar({
   }
 
   function registerWecomBotWebhookRoute(api) {
-    const botConfig = resolveWecomBotConfig(api);
-    if (!botConfig.enabled) return false;
-    if (!botConfig.token || !botConfig.encodingAesKey) {
+    const botConfigs = resolveWecomBotConfigs(api);
+    const enabledBotConfigs = (Array.isArray(botConfigs) ? botConfigs : []).filter((item) => item?.enabled === true);
+    if (enabledBotConfigs.length === 0) return false;
+
+    const signedBotConfigs = enabledBotConfigs.filter((item) => item?.token && item?.encodingAesKey);
+    if (signedBotConfigs.length === 0) {
       api.logger.warn?.("wecom(bot): enabled but missing token/encodingAesKey; route not registered");
       return false;
     }
 
-    const normalizedPath =
-      normalizePluginHttpPath(botConfig.webhookPath ?? "/wecom/bot/callback", "/wecom/bot/callback") ??
-      "/wecom/bot/callback";
-    ensureBotStreamCleanupTimer(botConfig.streamExpireMs, api.logger);
-    cleanupExpiredBotStreams(botConfig.streamExpireMs);
-
-    const handler = createWecomBotWebhookHandler({
-      api,
-      botConfig,
-      normalizedPath,
-      readRequestBody,
-      parseIncomingJson,
-      computeMsgSignature,
-      decryptWecom,
-      parseWecomBotInboundMessage,
-      describeWecomBotParsedMessage,
-      cleanupExpiredBotStreams,
-      getBotStream,
-      buildWecomBotEncryptedResponse,
-      markInboundMessageSeen,
-      buildWecomBotSessionId,
-      createBotStream,
-      upsertBotResponseUrlCache,
-      messageProcessLimiter,
-      executeInboundTaskWithSessionQueue,
-      processBotInboundMessage,
-      deliverBotReplyText,
-      finishBotStream,
-    });
-
-    api.registerHttpRoute({
-      path: normalizedPath,
-      auth: "plugin",
-      handler,
-    });
-
-    api.logger.info?.(`wecom(bot): registered webhook at ${normalizedPath}`);
-    return true;
+    const grouped = new Map();
+    const agentWebhookGroups = groupAccountsByWebhookPath(api);
+    const agentPathSet = new Set(
+      Array.from(agentWebhookGroups.keys()).map(
+        (path) => normalizePluginHttpPath(path ?? "/wecom/callback", "/wecom/callback") ?? "/wecom/callback",
+      ),
+    );
+    for (const botConfig of signedBotConfigs) {
+      const normalizedAccountId = String(botConfig?.accountId ?? "default").trim().toLowerCase() || "default";
+      const normalizedPath =
+        normalizePluginHttpPath(botConfig.webhookPath ?? "/wecom/bot/callback", "/wecom/bot/callback") ??
+        "/wecom/bot/callback";
+      const registerGroupedPath = (candidatePath) => {
+        const existing = grouped.get(candidatePath);
+        if (existing) existing.push(botConfig);
+        else grouped.set(candidatePath, [botConfig]);
+      };
+      registerGroupedPath(normalizedPath);
+
+      const normalizedDefaultPath = normalizePluginHttpPath(
+        buildDefaultBotWebhookPath(normalizedAccountId),
+        "/wecom/bot/callback",
+      );
+      if (normalizedDefaultPath && normalizedPath === normalizedDefaultPath) {
+        const legacyAliasPath =
+          normalizePluginHttpPath(buildLegacyBotWebhookPath(normalizedAccountId), "/webhooks/wecom") ??
+          "/webhooks/wecom";
+        if (legacyAliasPath !== normalizedPath) {
+          if (agentPathSet.has(legacyAliasPath)) {
+            api.logger.warn?.(
+              `wecom(bot): skip legacy alias ${legacyAliasPath} for account=${normalizedAccountId} (conflicts with agent webhook path)`,
+            );
+          } else {
+            registerGroupedPath(legacyAliasPath);
+            api.logger.info?.(
+              `wecom(bot): registered legacy alias ${legacyAliasPath} for account=${normalizedAccountId}`,
+            );
+          }
+        }
+      }
+    }
+
+    let registeredCount = 0;
+    for (const [normalizedPath, pathConfigs] of grouped.entries()) {
+      const maxStreamExpireMs = pathConfigs.reduce(
+        (acc, item) => Math.max(acc, Number(item?.streamExpireMs) || 0),
+        0,
+      );
+      ensureBotStreamCleanupTimer(maxStreamExpireMs || 600000, api.logger);
+      cleanupExpiredBotStreams(maxStreamExpireMs || 600000);
+
+      const handler = createWecomBotWebhookHandler({
+        api,
+        botConfigs: pathConfigs,
+        normalizedPath,
+        readRequestBody,
+        parseIncomingJson,
+        computeMsgSignature,
+        decryptWecom,
+        parseWecomBotInboundMessage,
+        describeWecomBotParsedMessage,
+        cleanupExpiredBotStreams,
+        getBotStream,
+        buildWecomBotEncryptedResponse,
+        markInboundMessageSeen,
+        buildWecomBotSessionId,
+        createBotStream,
+        upsertBotResponseUrlCache,
+        messageProcessLimiter,
+        executeInboundTaskWithSessionQueue,
+        processBotInboundMessage,
+        deliverBotReplyText,
+        finishBotStream,
+        recordInboundMetric,
+        recordRuntimeErrorMetric,
+      });
+
+      api.registerHttpRoute({
+        path: normalizedPath,
+        auth: "plugin",
+        handler,
+      });
+
+      const accountIds = pathConfigs.map((item) => String(item?.accountId ?? "default")).join(", ");
+      api.logger.info?.(`wecom(bot): registered webhook at ${normalizedPath} (accounts=${accountIds})`);
+      registeredCount += 1;
+    }
+    return registeredCount > 0;
+  }
+
+  function buildBotWebhookPathSet(api) {
+    const botPathSet = new Set();
+    const botConfigs = resolveWecomBotConfigs(api);
+    const enabledBotConfigs = (Array.isArray(botConfigs) ? botConfigs : []).filter((item) => item?.enabled === true);
+    for (const botConfig of enabledBotConfigs) {
+      const normalizedAccountId = String(botConfig?.accountId ?? "default").trim().toLowerCase() || "default";
+      const normalizedPath =
+        normalizePluginHttpPath(botConfig.webhookPath ?? "/wecom/bot/callback", "/wecom/bot/callback") ??
+        "/wecom/bot/callback";
+      botPathSet.add(normalizedPath);
+
+      const normalizedDefaultPath = normalizePluginHttpPath(
+        buildDefaultBotWebhookPath(normalizedAccountId),
+        "/wecom/bot/callback",
+      );
+      if (normalizedDefaultPath && normalizedPath === normalizedDefaultPath) {
+        const legacyAliasPath =
+          normalizePluginHttpPath(buildLegacyBotWebhookPath(normalizedAccountId), "/webhooks/wecom") ??
+          "/webhooks/wecom";
+        botPathSet.add(legacyAliasPath);
+      }
+    }
+    return botPathSet;
   }
 
   function registerWecomAgentWebhookRoutes(api) {
     const webhookGroups = groupAccountsByWebhookPath(api);
+    const grouped = new Map();
+    for (const [normalizedPath, accounts] of webhookGroups.entries()) {
+      grouped.set(normalizedPath, [...accounts]);
+    }
+
+    const botPathSet = buildBotWebhookPathSet(api);
     for (const [normalizedPath, accounts] of webhookGroups.entries()) {
+      for (const account of accounts) {
+        const normalizedAccountId = String(account?.accountId ?? "default").trim().toLowerCase() || "default";
+        const normalizedDefaultPath =
+          normalizePluginHttpPath(buildDefaultAgentWebhookPath(normalizedAccountId), "/wecom/callback") ??
+          "/wecom/callback";
+        if (normalizedPath !== normalizedDefaultPath) continue;
+
+        const legacyAliasPath =
+          normalizePluginHttpPath(buildLegacyAgentWebhookPath(normalizedAccountId), "/webhooks/app") ??
+          "/webhooks/app";
+        if (!legacyAliasPath || legacyAliasPath === normalizedPath) continue;
+        if (botPathSet.has(legacyAliasPath)) {
+          api.logger.warn?.(
+            `wecom: skip legacy agent alias ${legacyAliasPath} for account=${normalizedAccountId} (conflicts with bot webhook path)`,
+          );
+          continue;
+        }
+
+        const existing = grouped.get(legacyAliasPath);
+        if (existing) {
+          const duplicated = existing.some(
+            (item) =>
+              (String(item?.accountId ?? "default").trim().toLowerCase() || "default") === normalizedAccountId,
+          );
+          if (!duplicated) existing.push(account);
+        } else {
+          grouped.set(legacyAliasPath, [account]);
+        }
+        api.logger.info?.(`wecom: registered legacy agent alias ${legacyAliasPath} for account=${normalizedAccountId}`);
+      }
+    }
+
+    for (const [normalizedPath, accounts] of grouped.entries()) {
       const handler = createWecomAgentWebhookHandler({
         api,
         accounts,
@@ -115,6 +245,8 @@ export function createWecomRouteRegistrar({
         messageProcessLimiter,
         executeInboundTaskWithSessionQueue,
         processInboundMessage,
+        recordInboundMetric,
+        recordRuntimeErrorMetric,
       });
       api.registerHttpRoute({
         path: normalizedPath,

package/src/wecom/runtime-utils.js

@@ -4,8 +4,13 @@ export function requireEnv(name, fallback, processEnv = process.env) {
   return value;
 }
 
-export function buildWecomBotSessionId(userId) {
-  return `wecom-bot:${String(userId ?? "").trim().toLowerCase()}`;
+export function buildWecomBotSessionId(userId, accountId = "default") {
+  const normalizedUserId = String(userId ?? "").trim().toLowerCase();
+  const normalizedAccountId = String(accountId ?? "default").trim().toLowerCase() || "default";
+  if (normalizedAccountId === "default") {
+    return `wecom-bot:${normalizedUserId}`;
+  }
+  return `wecom-bot:${normalizedAccountId}:${normalizedUserId}`;
 }
 
 export function asNumber(value, fallback = null) {

package/src/wecom/webhook-adapter.js

@@ -67,11 +67,22 @@ export function parseWecomBotInboundMessage(payload) {
   const imageUrls = [];
   let fileUrl = "";
   let fileName = "";
+  let voiceUrl = "";
+  let voiceMediaId = "";
+  let voiceContentType = "";
 
   if (msgType === "text") {
     content = normalizeToken(payload?.text?.content);
   } else if (msgType === "voice") {
     content = normalizeToken(payload?.voice?.content);
+    voiceUrl = normalizeToken(
+      payload?.voice?.url ||
+        payload?.voice?.media_url ||
+        payload?.voice?.download_url ||
+        payload?.voice?.file_url,
+    );
+    voiceMediaId = normalizeToken(payload?.voice?.media_id || payload?.voice?.mediaid || payload?.voice?.id);
+    voiceContentType = normalizeToken(payload?.voice?.content_type || payload?.voice?.mime_type || payload?.voice?.format);
   } else if (msgType === "link") {
     const title = normalizeToken(payload?.link?.title);
     const description = normalizeToken(payload?.link?.description);
@@ -99,6 +110,51 @@ export function parseWecomBotInboundMessage(payload) {
           imageUrls.push(...itemImageUrls);
           parts.push("[图片]");
         }
+      } else if (itemType === "voice") {
+        const itemVoiceUrl = normalizeToken(
+          item?.voice?.url ||
+            item?.voice?.media_url ||
+            item?.voice?.download_url ||
+            item?.voice?.file_url,
+        );
+        const itemVoiceMediaId = normalizeToken(item?.voice?.media_id || item?.voice?.mediaid || item?.voice?.id);
+        const itemVoiceContentType = normalizeToken(
+          item?.voice?.content_type || item?.voice?.mime_type || item?.voice?.format,
+        );
+        if (itemVoiceUrl) {
+          voiceUrl = voiceUrl || itemVoiceUrl;
+          voiceMediaId = voiceMediaId || itemVoiceMediaId;
+          voiceContentType = voiceContentType || itemVoiceContentType;
+          parts.push("[语音]");
+        }
+      } else if (itemType === "file") {
+        const itemFileUrl = normalizeToken(
+          item?.file?.url ||
+            item?.file?.download_url ||
+            item?.file?.media_url ||
+            item?.file?.file_url,
+        );
+        const itemFileName = normalizeToken(item?.file?.name || item?.file?.filename);
+        if (itemFileUrl || itemFileName) {
+          fileUrl = fileUrl || itemFileUrl;
+          fileName = fileName || itemFileName;
+          const displayName = itemFileName || itemFileUrl || "附件";
+          parts.push(`[文件] ${displayName}`);
+        }
+      } else if (itemType === "link") {
+        const title = normalizeToken(item?.link?.title);
+        const description = normalizeToken(item?.link?.description);
+        const url = normalizeToken(item?.link?.url);
+        const linkText = [title ? `[链接] ${title}` : "", description, url].filter(Boolean).join("\n").trim();
+        if (linkText) parts.push(linkText);
+      } else if (itemType === "location") {
+        const latitude = normalizeToken(item?.location?.latitude);
+        const longitude = normalizeToken(item?.location?.longitude);
+        const name = normalizeToken(item?.location?.name || item?.location?.label);
+        const locationText = name ? `[位置] ${name} (${latitude}, ${longitude})` : `[位置] ${latitude}, ${longitude}`;
+        if (locationText.trim() !== "[位置] ,") {
+          parts.push(locationText);
+        }
       }
     }
     content = parts.join("\n").trim();
@@ -143,6 +199,9 @@ export function parseWecomBotInboundMessage(payload) {
     imageUrls: dedupeUrlList(imageUrls),
     fileUrl,
     fileName,
+    voiceUrl,
+    voiceMediaId,
+    voiceContentType,
     feedbackId,
     quote,
     isGroupChat: chatType === "group" || Boolean(chatId),
@@ -178,6 +237,8 @@ export function extractWecomXmlInboundEnvelope(msgObj) {
     fromUser: normalizeToken(msgObj.FromUserName),
     chatId: normalizeToken(msgObj.ChatId),
     msgId: normalizeToken(msgObj.MsgId),
+    eventType: normalizeLowerToken(msgObj.Event),
+    eventKey: normalizeToken(msgObj.EventKey),
     content: normalizeToken(msgObj.Content),
     mediaId: normalizeToken(msgObj.MediaId),
     picUrl: normalizeToken(msgObj.PicUrl),

package/src/wecom/webhook-bot.js

@@ -66,6 +66,32 @@ export async function webhookSendMarkdown({
   });
 }
 
+export async function webhookSendTemplateCard({
+  url,
+  key,
+  templateCard,
+  timeoutMs = 15000,
+  dispatcher,
+  fetchImpl = fetch,
+} = {}) {
+  const sendUrl = resolveWebhookBotSendUrl({ url, key });
+  if (!sendUrl) throw new Error("missing webhook bot url/key");
+  if (!templateCard || typeof templateCard !== "object") {
+    throw new Error("templateCard payload is required");
+  }
+  const body = {
+    msgtype: "template_card",
+    template_card: templateCard,
+  };
+  return postWebhookJson({
+    url: sendUrl,
+    body,
+    timeoutMs,
+    dispatcher,
+    fetchImpl,
+  });
+}
+
 export async function webhookSendImage({
   url,
   key,