微信机器人开发需要什么？从扫码接入到消息处理

开发前的准备清单

动手写代码之前，先把东西准备齐了：

硬件 & 账号

• 一个微信账号（实名 + 正常使用3个月以上，别用新号/买的号）
• 一台能跑Python/Java/Go的开发机
• 手机一台（扫码登录用）

软件 & 工具

• Python 3.8+（或Java 17+、Go 1.21+任选）
• requests 库（发HTTP请求）
• Flask / FastAPI（起Webhook回调服务）
• 内网穿透工具（ngrok / cpolar / frp，本地开发用）
• Postman（调接口测试用，强烈建议装）

API平台

• 注册WTAPI账号 → 领试用 → 控制台生成Token
• 记下Base URL：`WTKPI框架
• 记下Token值：控制台里复制，调用接口时Header要带

全部准备好，一共5件事。哪件没搞定先搞定再往下走。

接入四步走

整个流程就四步，每一步对应一个核心接口。

第一步：扫码登录

import requests, json

BASE = "https://wx.chuapi.com"
TOKEN = "your_token"

# 获取登录二维码
resp = requests.post(
    f"{BASE}/finder/v2/api/login/getLoginQrCode",
    headers={"X-finder-TOKEN": TOKEN, "Content-Type": "application/json"},
    data=json.dumps({
        "appId": "",           # 首次登录传空，系统自动创建设备
        "regionId": "440000"   # 你的地区ID，440000是广东省，选本地的
    })
)
result = resp.json()

if result["ret"] == 200:
    app_id = result["data"]["appId"]          # 保存好！后续所有接口都要用
    qr_base64 = result["data"]["qrImgBase64"] # 二维码图片base64
    uuid = result["data"]["uuid"]             # 轮询检测登录状态要用
    
    # 把qr_base64转成图片存本地，手机扫码
    import base64
    with open("login.png", "wb") as f:
        f.write(base64.b64decode(qr_base64))
    print("二维码已保存为login.png，请用微信扫码登录")
    print(f"⚠️  请保存appId: {app_id}")
else:
    print(f"获取二维码失败: {result['msg']}")

手机扫码后，要轮询检测登录状态：

import time

def check_login(app_id, uuid):
    """轮询检测登录状态，每5秒一次"""
    resp = requests.post(
        f"{BASE}/finder/v2/api/login/checkLogin",
        headers={"X-finder-TOKEN": TOKEN, "Content-Type": "application/json"},
        data=json.dumps({
            "appId": app_id,
            "uuid": uuid,
            "autoSliding": True   # Mac登录传True（自动滑块）
                                  # iPad登录传False（需人脸识别App配合）
        })
    )
    return resp.json()

# 轮询
while True:
    time.sleep(5)
    result = check_login(app_id, uuid)
    status = result["data"]["status"]
    
    if status == 2:
        print(f"✅ 登录成功！wxid={result['data']['loginInfo'].get('wxid')}")
        print(f"   记住appId={app_id}，下次登录还要用")
        break
    elif status == 1:
        print("⏳ 已扫码，等待手机确认...")
    else:
        print("⏳ 等待扫码中...")

第二步：发消息验证

登录成功后，先手动发一条消息验证通不通：

resp = requests.post(
    f"{BASE}/finder/v2/api/message/postText",
    headers={"X-finder-TOKEN": TOKEN, "Content-Type": "application/json"},
    data=json.dumps({
        "appId": "上面保存的app_id",
        "toWxid": "文件传输助手的wxid（先用这个测试）",
        "content": "Hello World！"
    })
)
result = resp.json()

if result["ret"] == 200:
    print("✅ 消息发送成功！去微信看看文件传输助手收到没")
else:
    print(f"❌ 发送失败: {result.get('msg')}")

如果成功，你微信上的文件传输助手应该能收到一条"Hello World！"。到这里，主动发消息这条链路就通了。

第三步：配Webhook收消息

发是主动，收是被动。你得在API平台控制台配一个回调URL，微信有新消息时API平台会POST推送到你的服务。

先写一个回调服务（Flask）：

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/callback", methods=["POST"])
def on_message():
    data = request.json
    msg_type = data.get("msgType")
    from_user = data.get("fromUser")
    content = data.get("content", "")
    print(f"📨 收到消息 [{from_user}]: {content} ({msg_type})")
    return jsonify({"ret": 200})  # 必须返回200，平台才知道收到了

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8080, debug=True)

本地跑起来之后，用ngrok暴露到公网：

# 安装ngrok（Windows下载exe，Mac用brew install ngrok）
ngrok http 8080

# 拿到类似这样的地址：
# Forwarding  https://abcd1234.ngrok-free.app -> http://localhost:8080

然后在API平台控制台 → Webhook配置里，把URL填成：https://abcd1234.ngrok-free.app/callback

第四步：跑通完整闭环

现在你可以：

1. 用小号发消息给机器人号
2. Flask控制台会打印出收到的消息
3. 在回调里加业务逻辑，比如关键词匹配调用postText回复

@app.route("/callback", methods=["POST"])
def on_message():
    data = request.json
    
    # 过滤：只处理文本消息，忽略自己发的
    if data.get("msgType") != "text":
        return jsonify({"ret": 200})
    
    from_user = data.get("fromUser")
    content = data.get("content", "")
    
    # 关键词匹配
    rules = {
        "你好": "您好！请问有什么可以帮您？",
        "帮助": "发送【价格】【售后】获取帮助",
        "价格": "产品详情请咨询官网～",
    }
    
    for kw, reply in rules.items():
        if kw in content:
            send_text(from_user, reply)
            break
    
    return jsonify({"ret": 200})

完整流程图

┌──────────────────────────────────────────────────────────┐
│                                                          │
│  ① 扫码登录                                              │
│     POST /login/getLoginQrCode → 拿appId和uuid           │
│     POST /login/checkLogin（轮询）→ 等status=2           │
│                                                          │
│  ② 主动发消息                                            │
│     POST /message/postText → 微信收到消息                 │
│                                                          │
│  ③ 被动收消息                                            │
│     用户发消息 → 微信服务器 → API平台解密                  │
│     → POST /callback（你的Flask）                         │
│                                                          │
│  ④ 业务处理                                              │
│     Flask收到 → 关键词/AI处理 → POST /message/postText回复 │
│                                                          │
└──────────────────────────────────────────────────────────┘

常见问题速查

Q: 新设备首夜掉线？
A: 24小时内掉一次是正常风控，第二天8点后重登即可稳定。重登必须传同一个appId取码，否则循环掉线。

Q: 消息发太快被限制？
A: 走队列串行，1分钟不超40条，不同目标间隔随机1-5秒。

Q: 回调收不到消息？
A: ① 检查ngrok地址是否还活着；② 检查控制台Webhook URL是否配对；③ 检查Flask服务是否在跑；④ 确保回调接口能返回 {"ret": 200}。

Q: iPad登录需要人脸识别App？
A: 是的。iPad登录时autoSliding要传false，服务端生成人脸滑块二维码，用人脸识别App扫码完成验证。Mac登录autoSliding传true即可自动通过。

Q: regionId选什么？
A: 选你服务器所在地区的ID，比如广东440000、北京110000、上海310000。别选异地的，容易秒掉。

Q: 回调里怎么区分单聊和群聊？
A: 看chatRoomId字段。单聊的chatRoomId为空或不出现，群聊的chatRoomId有值（群的wxid）。

到这里算什么水平？

能走完这四步，说明你已经：

• ✅ 搞定了API平台接入
• ✅ 理解了主动/被动两种通信方式
• ✅ 能跑通一个最简单的自动回复机器人
• ✅ 知道怎么排查常见问题

后面想加什么功能都是在这个骨架上添肉：加好友管理就调addContact接口，加朋友圈就调sendSns接口，加AI就接大模型，逻辑都是一样的。

---