@agentor/chat-wecom

English | 中文

Chat SDK 适配器，用于 企业微信 (WeCom) 消息集成。

功能特性

• Webhook (群机器人) — 通过 Webhook URL 推送消息到群聊
• Bot (智能机器人) — 支持回调 URL 和 WebSocket 长连接两种模式收发消息
• App (应用) — 发送应用消息、接收回调事件、管理 Access Token
• 富媒体支持 — 图片、语音、视频、文件的上传下载
• 卡片消息 — 将 Chat SDK 的 CardElement 转换为企业微信 Template Card
• 安全加密 — AES-256-CBC 加解密 + SHA1 签名校验

安装

# Install with npm
npm install chat @agentor/chat-wecom

# Install with yarn
yarn add chat @agentor/chat-wecom

# Install with pnpm
pnpm add chat @agentor/chat-wecom

快速开始

Webhook (群机器人)

单向推送消息到群聊：

import { createWeComWebhookAdapter } from "@agentor/chat-wecom";

const adapter = createWeComWebhookAdapter({
  key: process.env.WECOM_WEBHOOK_KEY!,
});

const threadId = adapter.encodeThreadId({ key: process.env.WECOM_WEBHOOK_KEY! });
const result = await adapter.postMessage(threadId, "Hello from @agentor/chat-wecom!");

Bot — WebSocket 长连接模式 (智能机器人)

通过 WebSocket 直连企业微信服务，无需公网端点：

import { createWeComBotAdapter } from "@agentor/chat-wecom";

const adapter = createWeComBotAdapter({
  botId: process.env.WECOM_BOT_WS_BOT_ID!,
  secret: process.env.WECOM_BOT_WS_SECRET!,
});

await adapter.initialize({
  processMessage: async (_adapter, threadId, factory) => {
    const message = await factory();
    await adapter.postMessage(threadId, message.text);
  },
});

// 断开连接
await adapter.disconnect();

Bot — 回调 URL 模式 (智能机器人)

通过 HTTP 回调接收和回复消息，需要公网可达的端点：

import { createWeComBotAdapter } from "@agentor/chat-wecom";

const adapter = createWeComBotAdapter({
  mode: "callback",
  token: process.env.WECOM_BOT_TOKEN!,
  encodingAESKey: process.env.WECOM_BOT_ENCODING_AES_KEY!,
});

await adapter.initialize({
  processMessage: async (_adapter, threadId, factory) => {
    const message = await factory();
    await adapter.postMessage(threadId, message.text);
  },
});

// 在 HTTP 服务器中处理回调
// adapter.handleWebhook(request) → Response

App (应用)

发送应用消息并接收回调事件：

import { createWeComAppAdapter } from "@agentor/chat-wecom";

const adapter = createWeComAppAdapter({
  corpId: process.env.WECOM_APP_CORP_ID!,
  corpSecret: process.env.WECOM_APP_CORP_SECRET!,
  agentId: Number(process.env.WECOM_APP_AGENT_ID!),
  token: process.env.WECOM_APP_TOKEN, // 接收回调时必填
  encodingAESKey: process.env.WECOM_APP_ENCODING_AES_KEY, // 接收回调时必填
});

// 发送消息
const threadId = adapter.encodeThreadId({
  corpId: process.env.WECOM_APP_CORP_ID!,
  userId: "user-id",
});
const result = await adapter.postMessage(threadId, "Hello from app!");

// 撤回消息
await adapter.deleteMessage(threadId, result.id);

// 获取 Access Token
const token = await adapter.getAccessToken();

环境变量

配置项

Webhook (群机器人)

Bot (智能机器人)

App (应用)

平台配置

Webhook (群机器人)

1. 在企业微信群聊中添加「群机器人」
2. 选择「自定义机器人」并创建
3. 复制 Webhook 地址中的 key 参数

Bot (智能机器人)

1. 登录企业微信管理后台
2. 进入「应用管理」→「智能机器人」创建机器人
3. 回调模式：配置回调 URL 并填写 Token 和 EncodingAESKey
4. WebSocket 模式：获取 Bot ID 和 Secret

App (应用)

1. 登录企业微信管理后台
2. 进入「应用管理」→「自建」创建应用
3. 获取 CorpId、CorpSecret、AgentId
4. 如需接收回调：在应用详情中配置「接收消息」的 URL、Token、EncodingAESKey

消息类型支持

接收消息

Webhook 为单向推送，不支持接收消息。App 不支持 file 类型回调（企业微信平台限制），视频和语音需通过企业微信内置录制功能发送。

发送消息

Webhook 和 Bot (回调) 的 Template Card 仅支持 text_notice 和 news_notice 两种类型。Bot (WS) 和 App 支持全部 5 种卡片类型。Bot (WS) 的媒体消息通过 respond_msg（回复消息）发送，主动推送 (send_msg) 仅支持 Markdown 和 Template Card。

媒体文件处理

媒体上传

import { uploadAppMedia, uploadWebhookMedia } from "@agentor/chat-wecom";

// 应用消息上传
const mediaId = await uploadAppMedia(accessToken, {
  data: imageBuffer,
  filename: "image.png",
  mimeType: "image/png",
});

// Webhook 上传
const mediaId = await uploadWebhookMedia(webhookKey, {
  data: fileBuffer,
  filename: "document.pdf",
});

媒体下载

import { downloadAppMedia, fetchEncryptedMedia } from "@agentor/chat-wecom";

// 通过 mediaId 下载应用消息媒体
const { data, filename } = await downloadAppMedia(accessToken, mediaId);

// 下载并解密 Bot 加密媒体（需要 aeskey）
const { data, filename } = await fetchEncryptedMedia(url, aeskey);

postMessage 会自动处理媒体上传流程：传入 FileUpload 时，先上传获取 media_id，再发送对应类型的媒体消息。

卡片消息

支持将 Chat SDK 的 CardElement 自动转换为企业微信 Template Card（5 种卡片类型）：

卡片类型根据 CardElement 内容自动推断：

• 包含多选/下拉 → multiple_interaction
• 包含单选 → vote_interaction
• 包含按钮 → button_interaction
• 包含图片 → news_notice
• 默认 → text_notice

整卡点击（card_action）

企业微信要求 text_notice / news_notice 的 card_action（整卡点击跳转）必填且必须是跳转，button_interaction 则可选。由于 CardElement 没有「整卡链接」字段，card_action 的 URL 按以下优先级解析：

1. 卡片的第一个链接（LinkElement / LinkButtonElement）
2. 头部图片（imageUrl）
3. 适配器的 cardActionUrl 配置
4. 内置默认（https://work.weixin.qq.com）

button_interaction 在卡片无链接/图片时省略 card_action（整卡不可点击）；text_notice / news_notice 始终设置 card_action（必填），无链接时回退到 cardActionUrl 或内置默认。

import type { CardElement } from "chat";

const card: CardElement = {
  type: "card",
  title: "审批通知",
  subtitle: "请审批以下申请",
  children: [
    {
      type: "fields",
      children: [{ type: "field", label: "申请人", value: "张三" }],
    },
    {
      type: "actions",
      children: [
        { type: "button", label: "同意", style: "primary", id: "approve" },
        { type: "button", label: "拒绝", style: "danger", id: "reject" },
      ],
    },
  ],
};

await adapter.postMessage(threadId, card);

卡片按钮回调闭环

button_interaction / vote_interaction / multiple_interaction 卡片的按钮点击，以 chat-sdk 标准的交互动作接入：用户点击后企业微信回调 template_card_event，适配器解析后调用 chat.processAction，ButtonElement.id 映射为 ActionEvent.actionId，用 chat.onAction(actionId, handler) 响应。

仅 App（应用） 模式支持按钮回调（Webhook 群机器人、Bot 模式无交互回调）。

回调 XML 中的 ResponseCode（72 小时有效、一次性）用于 updateTemplateCard 更新卡片状态（如按钮变「已处理」）。发送卡片时 /message/send 响应也会返回 response_code，二者均可用于更新。

import { isWeComAppAdapter, type WeComAppCallbackMessage } from "@agentor/chat-wecom";

// 1. 注册按钮点击处理器（actionId = ButtonElement.id）
chat.onAction("approve", async (event) => {
  const raw = event.raw as WeComAppCallbackMessage;
  console.log(`${event.user.userId} 点击 ${event.actionId}，taskId=${raw.taskId}`);

  // 2. 用回调里的 responseCode 把按钮变为不可点击
  if (isWeComAppAdapter(event.adapter) && raw.responseCode) {
    await event.adapter.updateTemplateCard({
      responseCode: raw.responseCode,
      replaceName: "已同意",
    });
  }
});

updateTemplateCard 参数：

投票/多选卡片的用户提交结果在 raw.selectedItems（{ questionKey, optionIds }[]）。

加解密

所有回调通信使用 AES-256-CBC 加密和 SHA1 签名校验：

import { encrypt, decrypt, calculateSignature, verifySignature } from "@agentor/chat-wecom";

const encrypted = await encrypt(encodingAESKey, "Hello", "receiveId");
const decrypted = await decrypt(encodingAESKey, encrypted, "receiveId");

const signature = await calculateSignature(token, timestamp, nonce, encrypted);
const valid = await verifySignature(token, timestamp, nonce, encrypted, signature);

不支持的操作

以下操作会抛出 NotImplementedError：

• editMessage — 所有适配器均不支持
• deleteMessage — 仅 App 适配器支持
• fetchMessages / fetchThread — 不支持
• addReaction / removeReaction — 不支持

License

MIT © Demo Macro