企业微信开发文档---企业微信机器人长连接开发

一、建立长连接完整流程

官方文档地址：https://developer.work.weixin.qq.com/document/path/101463

二、开发操作步骤

2.1 建立连接，编写对应的回调函数

复制代码

def start_websocket_connection() -> None:
    """发起 WebSocket 连接并保持运行。"""
    ws = websocket.WebSocketApp(
        WS_URL,
        on_open=on_open,  # 订阅鉴权
        on_message=on_message, # 收到服务端任意消息时触发。
        on_error=on_error,     # 连接/收发出现异常时触发。
        on_close=on_close,  # 连接关闭时触发
    )
    ws.run_forever()

2.2 on_open函数，发送订阅鉴权请求

复制代码

#请求示例：
{
    "cmd": "aibot_subscribe",
    "headers": {
        "req_id": "REQUEST_ID"
    },
    "body": {
        "bot_id": "BOTID",
        "secret": "SECRET"
    }
}

2.4 ws.send函数，发送消息给企业微信服务器

只负责发送，返回消息的on_message的回包里面

2.5 on_message函数，响应示例

复制代码

# 订阅成功后的响应示例
{
    "headers": {
        "req_id": "REQUEST_ID"
    },
    "errcode": 0,
    "errmsg": "ok"
}

# 用户发勇消息的响应示例
{
    "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"
        }
    }
}

字段	类型	说明
cmd	string	命令类型，固定值 `aibot_msg_callback`
headers.req_id	string	请求唯一标识，回复消息时需透传
body.msgid	string	本次回调的唯一性标志，用于事件排重
body.aibotid	string	智能机器人 BotID
body.chatid	string	会话 ID，仅群聊类型时返回
body.chattype	string	会话类型，`single` 单聊 / `group` 群聊
body.from.userid	string	消息发送者的 userid
body.msgtype	string	消息类型

2.6 订阅成功保持心跳

复制代码

{
    "cmd": "ping",
    "headers": {
        "req_id": "REQUEST_ID"
    }
}


threading.Event() 是 Python 标准库中用于线程间简单信号通信的同步原语。它内部维护一个布尔标志（初始为 False），线程可以等待该标志变为 True，也可以由其他线程将其设置为 True 或重置为 False。


wait(timeout=None)	阻塞当前线程，直到内部标志为 True。如果指定 timeout（秒），超时后即使标志仍为 False 也会返回 False。
set()	    将内部标志设为 True，并唤醒所有正在 wait() 的线程。
clear()	    将内部标志重置为 False。
is_set()	返回当前标志的状态（True/False）。
heartbeat_thread.is_alive()  用于判断该线程是否正在运行，（True/False）。

2.7消息回调和事件回调

维度	`aibot_msg_callback` （消息回调）	`aibot_event_callback` （事件回调）
触发时机	用户主动发送一条消息内容时（文本、图片、语音、文件等）	用户与机器人发生交互动作，但不产生消息文本时，用户进入与机器人的单聊界面、点击快捷回复按钮、对机器人回复进行"点赞/点踩"、机器人被添加到群聊