Loading... # 微信 iLink Bot SDK 技术文档 # 一、概述 ## 1. 项目简介 ### A. 是什么 weixin-bot 是一个微信 iLink Bot SDK，支持 Node.js 和 Python 两种语言实现。它为开发者提供了一套简洁的 API，让任何 Agent 可以在 5 分钟内接入微信消息收发功能。 ### B. 为什么需要它 传统的微信机器人接入面临以下痛点： - 协议复杂，需要深入理解微信 iLink Bot API - context_token 管理繁琐，处理不当会导致消息投递失败 - Session 过期需要手动重新登录 - 需要配置 Webhook 接收消息，部署复杂 weixin-bot SDK 通过封装底层协议细节，解决了这些问题： - 零配置，开箱即用 - 凭证自动保存和续期 - context_token 自动管理 - 长轮询收消息，无需 Webhook ### C. 应用场景 - AI Agent 接入微信作为交互渠道 - 客服机器人自动回复 - 群聊助手和消息监听 - 微信消息自动化处理 ## 2. 技术背景 ### A. iLink Bot API iLink Bot API 是微信提供的机器人接口协议，采用 HTTP 长轮询方式接收消息，通过 HTTP POST 发送消息。关键特性包括： - 扫码登录认证 - 长轮询获取更新 - context_token 上下文传递机制 - Typing 状态支持 ### B. 协议关键发现 SDK 开发过程中发现的关键协议细节： - context_token：回复消息时必须原样传回 API - sendtyping：唯一能触发"对方正在输入中"的方式 - message_state：GENERATING 状态在 API 层面可用，但微信客户端不渲染 - Session 过期：errcode 为 -14 时需要重新登录 # 二、系统架构 ## 1. 整体架构 ```mermaid graph TB Agent[Agent 应用] -->|调用| SDK[weixin-bot SDK] SDK -->|HTTP 长轮询| API[iLink Bot API] SDK -->|HTTP POST| API API -->|推送消息| User[微信用户] User -->|扫码/发消息| API SDK -->|保存凭证| Local[本地存储] ```  ## 2. 组件说明 - Agent 应用：使用 SDK 的上层应用，如 AI Agent、客服机器人 - weixin-bot SDK：封装 iLink Bot API 协议的 SDK 库 - iLink Bot API：微信提供的机器人接口服务 - 本地存储：保存登录凭证，避免重复扫码 ## 3. 交互流程 ```mermaid sequenceDiagram participant Agent as Agent 应用 participant SDK as weixin-bot SDK participant API as iLink Bot API participant User as 微信用户 Note over Agent,User: 1. 登录阶段 Agent->>SDK: bot.login() SDK->>API: GET /get_bot_qrcode?bot_type=3 API-->>SDK: 返回二维码 URL SDK-->>Agent: 终端显示二维码 User->>API: 微信扫码确认 API-->>SDK: 返回 bot_token + baseurl SDK-->>Agent: 登录成功，凭证已保存 Note over Agent,User: 2. 消息收发循环 Agent->>SDK: bot.run() loop 长轮询循环 SDK->>API: POST /getupdates (最多保持 35 秒) User->>API: 发送消息 "你好" API-->>SDK: 返回消息 + context_token SDK-->>Agent: 触发 onMessage(msg) Agent->>SDK: bot.sendTyping(userId) SDK->>API: POST /sendtyping Note over User: 显示 "对方正在输入中" Agent->>SDK: bot.reply(msg, "Echo: 你好") SDK->>API: POST /sendmessage (带 context_token) API-->>User: 推送回复消息 SDK->>API: POST /sendtyping (取消 typing) end Note over Agent,User: 3. 异常处理 API-->>SDK: 返回 errcode: -14 (Session 过期) SDK->>SDK: 自动触发重新登录 SDK->>API: 重新获取二维码和 token SDK-->>Agent: 自动恢复运行 ```  # 三、安装指南 ## 1. 系统要求 - Node.js：14+ 版本 - Python：3.7+ 版本 - 网络环境：可访问微信 iLink Bot API ## 2. Node.js 安装 ```bash npm install @pinixai/weixin-bot ``` ## 3. Python 安装 ```bash pip install weixin-bot-sdk ``` # 四、快速入门 ## 1. Node.js 示例 ```typescript import { WeixinBot } from '@pinixai/weixin-bot' const bot = new WeixinBot() await bot.login() bot.onMessage(async (msg) => { await bot.sendTyping(msg.userId) await bot.reply(msg, `Echo: ${msg.text}`) }) await bot.run() ``` ## 2. Python 示例 ```python from weixin_bot import WeixinBot bot = WeixinBot() bot.login() @bot.on_message async def handle(msg): await bot.send_typing(msg.user_id) await bot.reply(msg, f"Echo: {msg.text}") bot.run() ``` ## 3. 运行流程 1. 创建 WeixinBot 实例 2. 调用 login() 方法，终端显示二维码 3. 使用微信扫码确认登录 4. 注册消息处理回调 5. 调用 run() 启动长轮询循环 # 五、API 参考 ## 1. 核心方法 | 方法 | 参数 | 说明 | |------|------|------| | login() | force?: boolean | 扫码登录，已有凭证则自动跳过 | | onMessage() | handler: Function | 注册消息处理回调 | | reply() | msg, text | 回复消息，自动取消 typing 状态 | | send() | userId, text | 主动发消息，需已有 context_token | | sendTyping() | userId | 显示"对方正在输入中" | | stopTyping() | userId | 取消输入状态 | | run() | 无 | 启动长轮询循环 | | stop() | 无 | 停止运行 | ## 2. 消息对象 ```typescript interface Message { userId: string // 用户 ID text: string // 消息文本 contextToken: string // 上下文 token，SDK 自动管理 } ``` ## 3. 使用示例 ```typescript // 回复消息 await bot.reply(msg, "收到你的消息") // 主动发消息 await bot.send(userId, "你好") // 显示 typing 状态 await bot.sendTyping(userId) // 取消 typing 状态 await bot.stopTyping(userId) ``` # 六、高级特性 ## 1. context_token 自动管理 context_token 是 iLink Bot API 的关键机制： - API 返回消息时携带 context_token - 回复消息时必须原样传回，否则消息无法投递 - SDK 内部自动管理，开发者无需关心 ## 2. Typing 状态 sendtyping 是唯一能触发"对方正在输入中"的方式： ```typescript await bot.sendTyping(userId) // 开始输入状态 // ... 处理消息 ... await bot.reply(msg, text) // reply 会自动取消 typing ``` ## 3. Session 过期自动处理 当 Session 过期（errcode: -14）时： - SDK 自动检测到错误 - 自动触发重新登录流程 - 恢复后继续运行 ## 4. 凭证持久化 登录成功后，SDK 自动保存凭证： - bot_token - baseurl - 后续启动自动加载凭证，无需重复扫码 # 七、技术细节 ## 1. 长轮询机制 SDK 使用长轮询获取消息更新： - 请求 /getupdates 接口 - 最多保持 35 秒 - 有消息立即返回 - 无消息超时返回空数组 - 循环往复持续监听 ## 2. 消息投递保证 为保证消息成功投递： - 使用收到的 context_token 原样传回 - SDK 内部维护 userId 到 context_token 的映射 - 避免跨会话复用 token ## 3. 协议限制 以下是协议分析和使用中发现的限制： - message_state: GENERATING 在 API 层面可用，但微信客户端不渲染气泡更新，不建议使用 - sendtyping 是唯一可靠的 typing 触发方式 - Session 会定期过期，需要处理 -14 错误码 # 八、最佳实践 ## 1. 消息处理建议 ```typescript bot.onMessage(async (msg) => { try { // 1. 先显示 typing，提升用户体验 await bot.sendTyping(msg.userId) // 2. 处理业务逻辑 const response = await processMessage(msg.text) // 3. 回复消息（自动取消 typing） await bot.reply(msg, response) } catch (error) { console.error('处理消息失败:', error) } }) ``` ## 2. 错误处理 ```typescript bot.onMessage(async (msg) => { try { await bot.reply(msg, "处理中...") } catch (error) { if (error.code === -14) { console.log('Session 过期，SDK 会自动重连') } else { console.error('发送消息失败:', error) } } }) ``` ## 3. 资源清理 ```typescript // 优雅退出 process.on('SIGINT', async () => { console.log('正在停止 bot...') bot.stop() process.exit(0) }) ``` # 九、故障排查 ## 1. 常见问题 ### 问题：登录后收不到消息 - 检查网络连接 - 确认 run() 方法已调用 - 查看控制台是否有错误日志 ### 问题：消息发送失败 - 确认 context_token 有效 - 检查是否使用 reply() 方法而非 send() - 查看错误码和错误信息 ### 问题：频繁要求重新登录 - 检查 IP 是否被限制 - 确认账号状态正常 - Session 有效期可能较短，属于正常现象 ## 2. 日志调试 SDK 输出详细日志，方便调试： - 登录状态 - 消息收发 - 错误信息 # 十、生态资源 ## 1. 官方资源 - GitHub 仓库：https://github.com/epiral/weixin-bot - 协议文档：docs/protocol-spec.md（1200+ 行详细分析） ## 2. 示例项目 - Node.js Echo Bot：完整示例，含日志和 typing - Node.js 流式测试：GENERATING vs FINISH 测试 - Node.js Typing 测试：sendtyping vs GENERATING 对比 ## 3. 相关包 - @pinixai/weixin-bot：Node.js SDK - weixin-bot-sdk：Python SDK *** ## 参考资料 1. [epiral/weixin-bot - GitHub](https://github.com/epiral/weixin-bot) 最后修改：2026 年 03 月 22 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏