@wecom/aibot-node-sdk

企业微信智能机器人 Node.js SDK —— 基于 WebSocket 长连接通道，提供消息收发、流式回复、模板卡片、事件回调、文件下载解密等核心能力。

✨ 特性

🔗 WebSocket 长连接 — 基于 wss://openws.work.weixin.qq.com 内置默认地址，开箱即用
🔐 自动认证 — 连接建立后自动发送认证帧（botId + secret）
💓 心跳保活 — 自动维护心跳，连续未收到 ack 时自动判定连接异常
🔄 断线重连 — 指数退避重连策略（1s → 2s → 4s → ... → 30s 上限），支持自定义最大重连次数
📨 消息分发 — 自动解析消息类型并触发对应事件（text / image / mixed / voice / file）
🌊 流式回复 — 内置流式回复方法，支持 Markdown 和图文混排
🃏 模板卡片 — 支持回复模板卡片消息、流式+卡片组合回复、更新卡片
📤 主动推送 — 支持向指定会话主动发送 Markdown 或模板卡片消息，无需依赖回调帧
📡 事件回调 — 支持进入会话、模板卡片按钮点击、用户反馈等事件
⏩ 串行回复队列 — 同一 req_id 的回复消息串行发送，自动等待回执
文件下载解密 — 内置 AES-256-CBC 文件解密，每个图片/文件消息自带独立的 aeskey
🪵 可插拔日志 — 支持自定义 Logger，内置带时间戳的 DefaultLogger
📦 双模块格式 — 同时输出 CJS / ESM，附带完整 TypeScript 类型声明

📦 安装

npm install @wecom/aibot-node-sdk
# 或
yarn add @wecom/aibot-node-sdk

🚀 快速开始

import AiBot from '@wecom/aibot-node-sdk';
import type { WsFrame } from '@wecom/aibot-node-sdk';
import { generateReqId } from '@wecom/aibot-node-sdk';

// 1. 创建客户端实例
const wsClient = new AiBot.WSClient({
  botId: 'your-bot-id',       // 企业微信后台获取的机器人 ID
  secret: 'your-bot-secret',  // 企业微信后台获取的机器人 Secret
});

// 2. 建立连接（支持链式调用）
wsClient.connect();

// 3. 监听认证成功
wsClient.on('authenticated', () => {
  console.log('🔐 认证成功');
});

// 4. 监听文本消息并进行流式回复
wsClient.on('message.text', (frame: WsFrame) => {
  const content = frame.body.text?.content;
  console.log(`收到文本: ${content}`);

  const streamId = generateReqId('stream');

  // 发送流式中间内容
  wsClient.replyStream(frame, streamId, '正在思考中...', false);

  // 发送最终结果
  setTimeout(() => {
    wsClient.replyStream(frame, streamId, `你好！你说的是: "${content}"`, true);
  }, 1000);
});

// 5. 监听进入会话事件（发送欢迎语）
wsClient.on('event.enter_chat', (frame: WsFrame) => {
  wsClient.replyWelcome(frame, {
    msgtype: 'text',
    text: { content: '您好！我是智能助手，有什么可以帮您的吗？' },
  });
});

// 6. 优雅退出
process.on('SIGINT', () => {
  wsClient.disconnect();
  process.exit(0);
});

📖 API 文档

`WSClient`

核心客户端类，继承自 EventEmitter，提供连接管理、消息收发等功能。

构造函数

const wsClient = new WSClient(options: WSClientOptions);

方法

方法	说明	返回值
`connect()`	建立 WebSocket 连接，连接后自动认证	`this`（支持链式调用）
`disconnect()`	主动断开连接	`void`
`reply(frame, body, cmd?)`	通过 WebSocket 通道发送回复消息（通用方法），frame 类型为 `WsFrameHeaders`（即 `Pick<WsFrame, 'headers'>`），直接传入完整 `WsFrame` 对象也可兼容	`Promise<WsFrame>`
`replyStream(frame, streamId, content, finish?, msgItem?, feedback?)`	发送流式文本回复（便捷方法，支持 Markdown），frame 类型同上	`Promise<WsFrame>`
`replyWelcome(frame, body)`	发送欢迎语回复（支持文本或模板卡片），需在收到事件 5s 内调用	`Promise<WsFrame>`
`replyTemplateCard(frame, templateCard, feedback?)`	回复模板卡片消息	`Promise<WsFrame>`
`replyStreamWithCard(frame, streamId, content, finish?, options?)`	发送流式消息 + 模板卡片组合回复	`Promise<WsFrame>`
`updateTemplateCard(frame, templateCard, userids?)`	更新模板卡片（响应 template_card_event），需在收到事件 5s 内调用	`Promise<WsFrame>`
`sendMessage(chatid, body)`	主动发送消息（支持 Markdown 或模板卡片），无需依赖回调帧	`Promise<WsFrame>`
`downloadFile(url, aesKey)`	下载文件并使用 AES 密钥解密（aesKey 取自消息体），返回 Buffer 及文件名	`Promise<{ buffer: Buffer; filename?: string }>`

属性

属性	说明	类型
`isConnected`	当前 WebSocket 连接状态	`boolean`
`api`	内部 API 客户端实例（高级用途）	`WeComApiClient`

`replyStream` 详细说明

wsClient.replyStream(
  frame: WsFrameHeaders, // 收到的原始 WebSocket 帧（透传 req_id），也可直接传完整 WsFrame 对象
  streamId: string,     // 流式消息 ID（使用 generateReqId('stream') 生成）
  content: string,      // 回复内容（支持 Markdown）
  finish?: boolean,     // 是否结束流式消息，默认 false
  msgItem?: ReplyMsgItem[], // 图文混排项（仅 finish=true 时有效）
  feedback?: ReplyFeedback, // 反馈信息（仅首次回复时设置）
);

`replyWelcome` 详细说明

发送欢迎语回复，需在收到 event.enter_chat 事件 5 秒内调用，超时将无法发送。

// 文本欢迎语
wsClient.replyWelcome(frame, {
  msgtype: 'text',
  text: { content: '欢迎！' },
});

// 模板卡片欢迎语
wsClient.replyWelcome(frame, {
  msgtype: 'template_card',
  template_card: { card_type: 'text_notice', main_title: { title: '欢迎' } },
});

`replyTemplateCard` 详细说明

wsClient.replyTemplateCard(
  frame: WsFrameHeaders,    // 收到的原始 WebSocket 帧
  templateCard: TemplateCard, // 模板卡片内容
  feedback?: ReplyFeedback,  // 反馈信息（可选）
);

`replyStreamWithCard` 详细说明

wsClient.replyStreamWithCard(
  frame: WsFrameHeaders,  // 收到的原始 WebSocket 帧
  streamId: string,        // 流式消息 ID
  content: string,         // 回复内容（支持 Markdown）
  finish?: boolean,        // 是否结束流式消息，默认 false
  options?: {
    msgItem?: ReplyMsgItem[];       // 图文混排项（仅 finish=true 时有效）
    streamFeedback?: ReplyFeedback; // 流式消息反馈信息（首次回复时设置）
    templateCard?: TemplateCard;    // 模板卡片内容（同一消息只能回复一次）
    cardFeedback?: ReplyFeedback;   // 模板卡片反馈信息
  },
);

`updateTemplateCard` 详细说明

更新模板卡片，需在收到 event.template_card_event 事件 5 秒内调用。

wsClient.updateTemplateCard(
  frame: WsFrameHeaders,    // 对应事件的 WebSocket 帧（需包含该事件的 req_id）
  templateCard: TemplateCard, // 模板卡片内容（task_id 需与回调收到的 task_id 一致）
  userids?: string[],        // 要替换模版卡片消息的 userid 列表，不填则替换所有用户
);

`sendMessage` 详细说明

主动向指定会话推送消息，无需依赖收到的回调帧。

wsClient.sendMessage(
  chatid: string,  // 会话 ID，单聊填用户的 userid，群聊填对应群聊的 chatid
  body: SendMarkdownMsgBody | SendTemplateCardMsgBody, // 消息体
);

使用示例：

// 发送 Markdown 消息
await wsClient.sendMessage('userid_or_chatid', {
  msgtype: 'markdown',
  markdown: { content: '这是一条**主动推送**的消息' },
});

// 发送模板卡片消息
await wsClient.sendMessage('userid_or_chatid', {
  msgtype: 'template_card',
  template_card: { card_type: 'text_notice', main_title: { title: '通知' } },
});

`downloadFile` 使用示例

// aesKey 取自消息体中的 image.aeskey 或 file.aeskey
wsClient.on('message.image', async (frame: WsFrame) => {
  const body = frame.body;
  const { buffer, filename } = await wsClient.downloadFile(body.image?.url, body.image?.aeskey);
  console.log(`文件名: ${filename}, 大小: ${buffer.length} bytes`);
});

⚙️ 配置选项

WSClientOptions 完整配置：

参数	类型	必填	默认值	说明
`botId`	`string`	✅	—	机器人 ID（企业微信后台获取）
`secret`	`string`	✅	—	机器人 Secret（企业微信后台获取）
`reconnectInterval`	`number`	—	`1000`	重连基础延迟（毫秒），实际延迟按指数退避递增（1s → 2s → 4s → ... → 30s 上限）
`maxReconnectAttempts`	`number`	—	`10`	最大重连次数（`-1` 表示无限重连）
`heartbeatInterval`	`number`	—	`30000`	心跳间隔（毫秒）
`requestTimeout`	`number`	—	`10000`	HTTP 请求超时时间（毫秒）
`wsUrl`	`string`	—	`wss://openws.work.weixin.qq.com`	自定义 WebSocket 连接地址
`logger`	`Logger`	—	`DefaultLogger`	自定义日志实例

📡 事件列表

所有事件均通过 wsClient.on(event, handler) 监听：

事件	回调参数	说明
`connected`	—	WebSocket 连接建立
`authenticated`	—	认证成功
`disconnected`	`reason: string`	连接断开
`reconnecting`	`attempt: number`	正在重连（第 N 次）
`error`	`error: Error`	发生错误
`message`	`frame: WsFrame<BaseMessage>`	收到消息（所有类型）
`message.text`	`frame: WsFrame<TextMessage>`	收到文本消息
`message.image`	`frame: WsFrame<ImageMessage>`	收到图片消息
`message.mixed`	`frame: WsFrame<MixedMessage>`	收到图文混排消息
`message.voice`	`frame: WsFrame<VoiceMessage>`	收到语音消息
`message.file`	`frame: WsFrame<FileMessage>`	收到文件消息
`event`	`frame: WsFrame<EventMessage>`	收到事件回调（所有事件类型）
`event.enter_chat`	`frame: WsFrame<EventMessage>`	收到进入会话事件（用户当天首次进入单聊会话）
`event.template_card_event`	`frame: WsFrame<EventMessage>`	收到模板卡片事件（用户点击卡片按钮）
`event.feedback_event`	`frame: WsFrame<EventMessage>`	收到用户反馈事件

📋 消息类型

SDK 支持以下消息类型（MessageType 枚举）：

类型	值	说明
`Text`	`'text'`	文本消息
`Image`	`'image'`	图片消息（URL 已加密，使用消息中的 `image.aeskey` 解密）
`Mixed`	`'mixed'`	图文混排消息（包含 text / image 子项）
`Voice`	`'voice'`	语音消息（已转文本）
`File`	`'file'`	文件消息（URL 已加密，使用消息中的 `file.aeskey` 解密）

SDK 支持以下事件类型（EventType 枚举）：

类型	值	说明
`EnterChat`	`'enter_chat'`	进入会话事件：用户当天首次进入机器人单聊会话
`TemplateCardEvent`	`'template_card_event'`	模板卡片事件：用户点击模板卡片按钮
`FeedbackEvent`	`'feedback_event'`	用户反馈事件：用户对机器人回复进行反馈

消息帧结构（`WsFrame<T>`）

interface WsFrame<T = any> {
  cmd?: string;              // 命令类型
  headers: {
    req_id: string;          // 请求 ID（回复时需透传）
    [key: string]: any;
  };
  body?: T;                  // 消息体（泛型，默认 any）
  errcode?: number;          // 响应错误码
  errmsg?: string;           // 响应错误信息
}

消息体结构（`BaseMessage`）

interface BaseMessage {
  msgid: string;             // 消息唯一标识
  aibotid: string;           // 机器人 ID
  chatid?: string;           // 群聊 ID（群聊时返回）
  chattype: 'single' | 'group';  // 会话类型
  from: { userid: string };  // 发送者信息
  create_time?: number;      // 事件产生的时间戳
  response_url?: string;     // 支持主动回复消息的临时 url
  msgtype: string;           // 消息类型
  quote?: QuoteContent;      // 引用消息内容
}

事件消息结构（`EventMessage`）

interface EventMessage {
  msgid: string;             // 本次回调的唯一性标志
  create_time: number;       // 事件产生的时间戳
  aibotid: string;           // 智能机器人 ID
  chatid?: string;           // 会话 ID（仅群聊时返回）
  chattype?: 'single' | 'group';  // 会话类型
  from: EventFrom;           // 事件触发者信息（含 userid、corpid?）
  msgtype: 'event';          // 消息类型，固定为 event
  event: EventContent;       // 事件内容
}

🪵 自定义日志

实现 Logger 接口即可自定义日志输出：

interface Logger {
  debug(message: string, ...args: any[]): void;
  info(message: string, ...args: any[]): void;
  warn(message: string, ...args: any[]): void;
  error(message: string, ...args: any[]): void;
}

使用示例：

const wsClient = new AiBot.WSClient({
  botId: 'your-bot-id',
  secret: 'your-bot-secret',
  logger: {
    debug: () => {},  // 静默 debug 日志
    info: console.log,
    warn: console.warn,
    error: console.error,
  },
});

📂 项目结构

aibot-node-sdk/
├── src/
│   ├── index.ts             # 入口文件，统一导出
│   ├── client.ts            # WSClient 核心客户端
│   ├── ws.ts                # WebSocket 长连接管理器
│   ├── message-handler.ts   # 消息解析与事件分发
│   ├── api.ts               # HTTP API 客户端（文件下载）
│   ├── crypto.ts            # AES-256-CBC 文件解密
│   ├── logger.ts            # 默认日志实现
│   ├── utils.ts             # 工具方法（generateReqId 等）
│   ├── types.ts             # 类型重导出
│   └── types/
│       ├── index.ts          # 类型统一导出
│       ├── config.ts         # 配置选项类型
│       ├── event.ts          # 事件映射类型
│       ├── message.ts        # 消息相关类型
│       ├── api.ts            # API/WebSocket 帧类型
│       └── common.ts         # 通用类型（Logger）
├── examples/
│   └── basic.ts             # 基础使用示例
├── package.json
├── tsconfig.json
├── rollup.config.mjs        # Rollup 构建配置
└── yarn.lock

🔧 开发

# 安装依赖
yarn install

# 开发模式（监听文件变化）
yarn dev

# 构建
yarn build

# 运行示例
yarn example

🦐 其他语言

wecom-aibot-go-sdk: 企业微信智能机器人 Go SDK

📄 License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

@wecom/aibot-node-sdk

✨ 特性

📦 安装

🚀 快速开始

📖 API 文档

`WSClient`

构造函数

方法

属性

`replyStream` 详细说明

`replyWelcome` 详细说明

`replyTemplateCard` 详细说明

`replyStreamWithCard` 详细说明

`updateTemplateCard` 详细说明

`sendMessage` 详细说明

`downloadFile` 使用示例

⚙️ 配置选项

📡 事件列表

📋 消息类型

消息帧结构（`WsFrame<T>`）

消息体结构（`BaseMessage`）

事件消息结构（`EventMessage`）

🪵 自定义日志

📂 项目结构

🔧 开发

🦐 其他语言

📄 License

Name		Name	Last commit message	Last commit date
examples		examples
src		src
.gitignore		.gitignore
README.md		README.md
package.json		package.json
rollup.config.mjs		rollup.config.mjs
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

FilesExpand file tree

Directory actions

More options

Directory actions

More options

Latest commit

History

Folders and files

README.md

@wecom/aibot-node-sdk

✨ 特性

📦 安装

🚀 快速开始

📖 API 文档

WSClient

构造函数

方法

属性

replyStream 详细说明

replyWelcome 详细说明

replyTemplateCard 详细说明

replyStreamWithCard 详细说明

updateTemplateCard 详细说明

sendMessage 详细说明

downloadFile 使用示例

⚙️ 配置选项

📡 事件列表

📋 消息类型

消息帧结构（WsFrame<T>）

消息体结构（BaseMessage）

事件消息结构（EventMessage）

🪵 自定义日志

📂 项目结构

🔧 开发

🦐 其他语言

📄 License

`WSClient`

`replyStream` 详细说明

`replyWelcome` 详细说明

`replyTemplateCard` 详细说明

`replyStreamWithCard` 详细说明

`updateTemplateCard` 详细说明

`sendMessage` 详细说明

`downloadFile` 使用示例

消息帧结构（`WsFrame<T>`）

消息体结构（`BaseMessage`）

事件消息结构（`EventMessage`）