企业微信智能机器人Bot长连接API模式配置全攻略，支持流式消息对接Openclaw

企业微信智能机器人支持两种API模式接收消息回调：Webhook短连接模式和WebSocket长连接模式。相比之下，WebSocket长连接具有更低延迟和更高实时性，特别适合无公网IP或高实时性需求的场景。本文将深入解析企业微信智能机器人长连接API模式配置流程以及应用场景。

1️⃣ WebSocket长连接与短连接对比

在选择API接入模式时，可以从以下对比表中明确长连接的显著优势：

• 连接方式：长连接复用已建立的连接，而短连接需每次重新建立。
• 延迟：长连接具有更低的延迟，实时性更强。
• 服务端要求：长连接无固定公网IP限制，无需公网访问URL。
• 复杂度：长连接需维护心跳机制，有一定开发复杂度。
• 加解密：长连接无需处理消息加解密，简化开发流程。

综上所述，长连接方式更加适合需要高实时性或在内网环境运行的智能机器人应用场景。

2️⃣ 长连接的适用场景

推荐在以下场景中采用WebSocket长连接模式：

• 🔐 无公网IP限制或需要低延迟的环境（如内网服务器）。
• ⏱ 高实时性要求的应用场景，例如及时通知或互动机器人。
• 💡 需简化开发流程，减少消息加解密逻辑。

3️⃣ 长连接配置流程

从开启长连接API模式到建立连接的完整流程如下：

🌐 开启长连接API模式

在企业微信管理后台按照以下步骤完成开启：

1. 进入智能机器人的配置页面。
2. 选择「API模式」，并勾选「长连接方式」。
3. 记下「BotID」和「Secret」凭证，这是后续建立连接的关键。

🔑 获取凭证

需要以下凭证以完成身份校验：

• BotID: 机器人唯一标识，用于标识连接身份。
• Secret: 长连接专用密钥，请妥善保管避免泄露。

注意： API模式只能选择一种方式，切换模式会导致原有连接失效。

4️⃣ 长连接建立和维护

🔗 建立WebSocket连接

前往WebSocket地址：wss://openws.work.weixin.qq.com 发起连接。连接成功后需发送订阅请求以完成认证。

{
    "cmd": "aibot_subscribe",
    "headers": {
        "req_id": "REQUEST_ID"
    },
    "body": {
        "bot_id": "BOTID",
        "secret": "SECRET"
    }
}

响应示例：认证成功将返回以下消息：

{
    "headers": {
        "req_id": "REQUEST_ID"
    },
    "errcode": 0,
    "errmsg": "ok"
}

🩺 心跳保活配置

为了确保连接连续性，需每隔30秒发送心跳请求（ping）以维持长连接状态。开发者需监控心跳状态并处理断线重连。

5️⃣ 消息回调与处理

📨 接收消息回调

用户向机器人发送单聊/群聊消息时，企业微信会推送消息回调。例如，以下为文本消息的回调结构：

{
    "cmd": "aibot_msg_callback",
    "headers": {
        "req_id": "REQUEST_ID"
    },
    "body": {
        "msgid": "MSGID",
        "aibotid": "AIBOTID",
        "chatid": "CHATID",
        "chattype": "group",
        "from": {
            "userid": "USERID"
        },
        "msgtype": "text",
        "text": {
            "content": "@RobotA hello robot"
        }
    }
}

6️⃣ 使用建议与注意事项

• 📋 确保每个机器人只能建立一个WebSocket连接。
• 🚦 避免频繁发送订阅请求，可能触发系统限制。
• 🛠 建议配置主备节点实现高可用，而非建立多连接。
• 🔒 谨慎保管长连接凭证，防止因泄露导致安全隐患。

企业微信智能机器人的长连接模式不仅提升了通信的实时性，还减少了对公网资源的依赖，使开发者能够更轻松地开发出高效、稳定的智能机器人。如果有特定需求，长连接无疑是更优的选择。