微信机器人REST API调用教程

2601_96922865

173人浏览 · 2026-09-17 13:19:55

2601_96922865 · 2026-09-17 13:19:55 发布

一、REST API 调用的基本认知

调用微信机器人的 REST API，本质上就是发 HTTP 请求。不管你用 Python、Java、Go 还是 Node.js，底层逻辑完全一样：拼一个 URL、带上请求头、塞好 JSON body、POST 出去、解析返回值。

这篇文章用最通用的 curl 做演示，因为 curl 贴到终端就能跑，没有任何语言门槛。理解了 curl 版本，换任何语言只是换个 HTTP 客户端的事。

二、三个固定要素

不管调哪个接口，有三样东西是固定的：

要素	值	说明
Base URL	`WTAPI框架	所有接口的域名前缀
认证头	`X-finder-TOKEN: 你的Token`	放在请求头里，每个请求都要带
响应格式	`{"ret": 200, "msg": "操作成功", "data": {...}}`	ret 为 200 表示成功

请求体统一用 JSON 格式，Content-Type 设为 application/json。

三、登录：获取二维码 + 确认状态

第一步：获取登录二维码

curl -X POST https://wx.chuapi.com/finder/v2/api/login/getLoginQrCode \
  -H "Content-Type: application/json" \
  -H "X-finder-TOKEN: 你的Token" \
  -d '{
    "appId": "",
    "regionId": "440000"
  }'

首次登录时 appId 传空字符串，服务端会分配一个新的。regionId 填账号常用地区的省份代码。

返回值核心字段：

{
  "ret": 200,
  "msg": "操作成功",
  "data": {
    "appId": "wxid_xxx分配的应用ID",
    "uuid": "会话唯一标识",
    "qrImgUrl": "二维码图片地址"
  }
}

data.appId 必须保存，后续所有请求都要用。

第二步：轮询确认登录

curl -X POST https://wx.chuapi.com/finder/v2/api/login/checkLogin \
  -H "Content-Type: application/json" \
  -H "X-finder-TOKEN: 你的Token" \
  -d '{
    "appId": "上一步拿到的appId",
    "uuid": "上一步拿到的uuid",
    "autoSliding": true
  }'

返回值里的 status 字段：

status 值	含义
0	等待扫码
1	已扫码，待确认
2	登录成功
3	已过期，需重新获取二维码

建议每 2 秒轮询一次，status 为 2 时停止。

四、发送消息

发送文本消息

curl -X POST https://wx.chuapi.com/finder/v2/api/message/postText \
  -H "Content-Type: application/json" \
  -H "X-finder-TOKEN: 你的Token" \
  -d '{
    "appId": "你的appId",
    "toWxid": "对方微信ID或群ID",
    "content": "你好，这是一条测试消息"
  }'

toWxid 填好友的 wxid 发私聊，填群的 chatroomId 发群消息。

发送图片消息

curl -X POST https://wx.chuapi.com/finder/v2/api/message/postImage \
  -H "Content-Type: application/json" \
  -H "X-finder-TOKEN: 你的Token" \
  -d '{
    "appId": "你的appId",
    "toWxid": "对方微信ID",
    "imgUrl": "https://example.com/image.png"
  }'

imgUrl 需要是公网可访问的图片地址。

五、获取通讯录和群列表

获取好友列表

curl -X GET https://wx.chuapi.com/finder/v2/api/contact/getContactList \
  -H "X-finder-TOKEN: 你的Token" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "你的appId"
  }'

返回好友列表，每条记录包含 wxid、昵称、备注等信息。

获取群聊列表

curl -X GET https://wx.chuapi.com/finder/v2/api/chatroom/getChatRoomList \
  -H "X-finder-TOKEN: 你的Token" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "你的appId"
  }'

这里有个细节：接口只返回已保存到通讯录的群。没保存的群需要先通过群内消息的回调拿到 chatRoomId，再用它来操作。

六、回调消息接收

回调不是你主动请求，而是平台主动 POST 到你配置的服务器地址。

收到的数据长这样：

{
  "appId": "你的appId",
  "msgType": 1,
  "fromUser": "发送者wxid",
  "nickName": "发送者昵称",
  "content": "消息内容",
  "createTime": 1697000000,
  "chatRoomId": ""
}

chatRoomId 为空表示私聊消息，有值表示群消息。

回调必须返回 {"ret": 200}，否则平台会认为推送失败并重发：

# 用 Python 起一个最简单的回调接收服务
python3 -m http.server 8080
# 然后把你的公网地址 + 端口配到平台后台

实际业务里建议用 Flask、Express 等框架接收，保证快速响应。

七、通用响应处理

所有接口的返回值结构一致，写一个通用的判断逻辑就够：

解析返回 JSON
├── ret == 200 → 成功，从 data 里取业务数据
├── ret != 200 → 失败，看 msg 字段的错误原因
└── 网络超时 → 记日志，不要立刻重试

常见非 200 的情况：

场景	表现
Token 错误或过期	ret 非 200，msg 提示鉴权失败
appId 未登录	ret 非 200，msg 提示需要登录
频率超限	ret 非 200，msg 提示频率限制
参数缺失	ret 非 200，msg 指出缺哪个字段

八、调用频率与重试策略

REST API 调用最怕两件事：发太快和疯狂重试。

频率控制

操作	建议频率
发送消息	1 分钟 ≤ 40 条，间隔随机 1~5 秒
获取列表	5 分钟一次，别频繁拉
轮询登录状态	2 秒一次，登录成功后停止

重试策略

接口返回非 200 时，不要立刻重试。正确做法：

记录错误日志（时间、接口、参数、返回值）
如果是网络超时，等 10 秒后重试一次
如果是业务错误（如频率限制），等待 60 秒
4 连续失败 3 次以上，暂停发送并告警

九、curl 到代码的转换

理解了 curl 的结构，转成任何语言都很直接。对照关系：

curl 部分	代码对应
`-X POST`	设置 HTTP 方法为 POST
`-H "X-finder-TOKEN: xxx"`	请求头加 Token
`-d '{...}'`	请求体设为 JSON 字符串
返回的 JSON	解析后取 `ret` 判断成功

比如 Python 版：

import requests

resp = requests.post(
    "https://wx.chuapi.com/finder/v2/api/message/postText",
    headers={
        "Content-Type": "application/json",
        "X-finder-TOKEN": "你的Token"
    },
    json={
        "appId": "你的appId",
        "toWxid": "对方wxid",
        "content": "你好"
    }
)
result = resp.json()
if result["ret"] == 200:
    print("发送成功")