企业微信智能机器人 API 模式

企业微信“智能机器人 API 模式”是面向单聊和群聊 @机器人 的正式双向通道，与“消息推送（原群机器人）”不是同一种能力。本文依据 2026 年更新的企业微信官方资料整理，核验日期为 2026-09-08；未在真实企业创建机器人。

能力边界

能力	消息推送（原群机器人）	自建应用消息/回调	智能机器人 API 模式
固定群单向通知	是	应用会话或应用管理的群	可主动推送，但不是最简通知入口
接收用户发给机器人的消息	否	可接收发给应用的消息/事件	是，单聊或群聊 `@机器人`
AI 对话与流式回复	否	可自行实现，但协议较通用	官方提供被动、主动及长连接流式机制
监听任意群聊	否	否	否，只处理与机器人的交互

智能机器人不代表必须使用企业微信内置模型。API 模式可以把消息交给规则引擎、业务 API 或任意 LLM。

准备条件

企业微信已开通智能机器人能力，操作者有相应创建和配置权限。
有一个内部测试群或测试成员，能把智能机器人加入/用于会话。
二选一准备接入环境：Webhook 需要公网 HTTPS URL、Token、EncodingAESKey；长连接需要 BotID、Secret 和常驻 SDK 进程。
服务端能持久化事件去重键、会话上下文和异步任务状态。

后台能力会按企业版本、灰度和管理员策略变化。如果管理后台没有“智能机器人”或“API 模式”，先由企业管理员确认功能可用性，不要改用消息推送 Webhook 冒充对话入口。

配置步骤

方案 A：Webhook（短连接）

在企业微信管理后台创建智能机器人并开启 API 模式。
选择“设置接收消息 URL”，填写公网 HTTPS URL、Token 与 EncodingAESKey。
按“回调和回复的加解密方案”实现 URL 验证、签名校验、消息解密和加密回复。
保存配置后，在测试单聊发送 /ping，或在测试群 @机器人 /ping。

Webhook 每次回调建立 HTTP 连接，需要公网入口并处理加解密，但服务端无状态、易水平扩展。

方案 B：WebSocket（长连接）

在 API 模式中选择“长连接”，获取 BotID 和 Secret。
Node.js 安装官方 @wecom/aibot-node-sdk；Python 安装 wecom-aibot-python-sdk。
用 SDK 建立订阅，处理 aibot_msg_callback 与相关事件。
实现心跳、断线重连和多实例连接管理。官方建议心跳间隔为 30 秒。

长连接不要求固定公网 IP，也无需自行处理回调消息加解密；但必须维护连接和心跳。官方文档指出长连接与 Webhook 是 API 模式的两种接收方式，应按部署条件选一种主路径。

接收消息

用户向机器人单聊，或在群聊中 @机器人 时触发消息回调。Webhook 解密后的消息与长连接的 aibot_msg_callback 都应标准化成：事件 ID、会话 ID、用户 ID、消息类型、文本、引用关系和回复句柄。

Webhook 回调可提供 response_url；官方规定每个 response_url 只能调用一次，有效期 1 小时。长连接则通过 SDK 的回复/发送动作返回消息，流式响应需要持续主动推送，直到 finish=true。

使用官方回调 ID 做事件去重；若某类回调没有单独事件 ID，则组合消息 ID、会话 ID 和事件类型。会话键推荐 wecom:{corpId}:{chatId}，单聊再按用户隔离。

使用 response_url 主动回复

下面的 URL 来自已解密的当前回调，只能使用一次。不要将它写入长期日志或会话历史。

curl -X POST 'RESPONSE_URL' \
  -H 'Content-Type: application/json' \
  -d '{"msgtype":"markdown","markdown":{"content":"pong"}}'

const response = await fetch(process.env.RESPONSE_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ msgtype: 'markdown', markdown: { content: 'pong' } }),
});
const result = await response.json();
if (!response.ok || result.errcode !== 0) throw new Error(JSON.stringify(result));

import os
import requests

response = requests.post(
    os.environ["RESPONSE_URL"],
    json={"msgtype": "markdown", "markdown": {"content": "pong"}},
    timeout=15,
)
response.raise_for_status()
result = response.json()
if result.get("errcode") != 0:
    raise RuntimeError(result)

普通 API 双向回复

最小业务流是：收到 /ping，验证用户与会话，立即被动回复 pong，或把任务入队后使用回调里的 response_url 主动回复。确定性 /status、工单查询、审批命令同样适用，不需要 LLM。

Webhook 被动回复必须遵循官方加密格式和时限；耗时业务不要阻塞回调。长连接模式通过 SDK 回复普通消息，不能直接照搬 HTTP XML/加密响应代码。

传统自建应用也可以配置“接收消息”回调并回复发给应用的消息，但它不等于监听任意群，也不具备智能机器人专用的流式回复体验。新建 AI 对话优先评估智能机器人 API 模式。

AI 对话扩展

const conversationKey = `wecom:${corpId}:${normalized.chatId}`;
const answer = await generateReply({
  messages: await history.withUserMessage(conversationKey, normalized.text),
  signal: AbortSignal.timeout(20_000),
});
await normalized.reply(answer);

Webhook 模式下，先快速完成平台确认，再在 1 小时且单次调用约束内使用 response_url。长连接模式可按官方协议逐步更新流式内容并最终设置 finish=true；连接中断或模型失败时必须结束占位状态或发送失败提示。

安全与可靠性

Webhook 先验签再解密，使用官方加解密库并校验企业/机器人接收方标识。
BotID、Secret、Token、EncodingAESKey 和 response_url 全部按敏感凭据处理。
长连接使用官方 SDK，落实 30 秒心跳、断线重连和连接数量限制；多实例不要无控制抢占。
做事件去重和会话串行，确保一次性的 response_url 不会被两个 Worker 同时消费。
群聊仅响应 @机器人，对模型工具调用按企业、成员和业务资源重新鉴权，防范提示词注入。
Markdown 最长字节数、媒体大小和发送频率遵循官方当前限制；超限前在本地截断或分段。

常见问题

后台只有“消息推送”，没有智能机器人 API 模式：两者不是同一功能。让企业管理员确认版本、灰度和权限，不要用群通知 Webhook 接收消息。

response_url 第二次调用失败：官方限制每个 URL 只能调用一次，有效期 1 小时。并发任务应先原子占用回复句柄。

长连接收不到群消息：确认机器人已用于该会话，并要求用户在群内 @机器人；它不会监听所有群消息。

Webhook URL 校验通过但消息解密失败：检查 Token、EncodingAESKey、签名参数、原始请求体和接收方 ID 是否属于同一个机器人配置。