个人微信API能力清单：消息/好友/群/朋友圈接口一览

前言

做过微信相关业务开发的同学都知道，官方的微信开放平台主要面向公众号、小程序和企业微信生态，对于个人微信账号能力的 API 支持几乎为零。但在实际项目中，客服机器人、私域运营助手、消息转发通知系统等场景往往需要操作个人微信账号——发消息、加好友、维护群聊、读取朋友圈。

这类需求催生了一类基于协议层封装的个人微信 API 服务，将微信客户端的核心行为抽象为标准 HTTP 接口，开发者通过 REST 调用即可完成原本只能手动完成的操作。本文以接口能力维度为主线，系统梳理个人微信 API 通常涵盖的四大模块：消息收发、好友管理、群聊管理、朋友圈交互，并附上可参考的调用示例，帮助开发者快速建立完整的能力认知。

声明：个人微信 API 的使用须遵守微信用户协议，严禁用于批量骚扰、垃圾营销等违规场景。开发者应在合法合规的业务场景内使用相关能力。

一、登录与设备管理

个人微信 API 的一切能力都建立在已登录的微信账号之上。接口服务通常以"设备"为单位管理账号状态，每个账号扫码登录后获得一个 appId（设备标识），后续所有接口都携带这个 appId 表明操作的是哪个账号。

1.1 扫码登录流程

pythonimport requests
import time

BASE  = "https://你的接口域名"   # 注册后在官方文档获取
TOKEN = "你的Token"
HEADERS = {"token": TOKEN}       # 鉴权字段名以官方文档为准

# 第一步：获取二维码
resp = requests.post(f"{BASE}/login/getLoginQrCode", headers=HEADERS, json={})
qr_data = resp.json()["data"]   # 含 base64 图片和 loginKey

# 第二步：轮询登录结果
login_key = qr_data["loginKey"]
app_id = None
while True:
    r = requests.post(f"{BASE}/login/checkLogin",
                      headers=HEADERS,
                      json={"loginKey": login_key})
    result = r.json()
    if result["ret"] == 200 and result["data"].get("appId"):
        app_id = result["data"]["appId"]
        break
    time.sleep(2)

# 第三步：注册回调
requests.post(f"{BASE}/tools/setCallback",
              headers=HEADERS,
              json={"appId": app_id, "callbackUrl": "https://你的服务器/webhook"})

# 代码为示例，具体接口/字段以官方文档为准

登录成功后，平台会把该账号收到的所有消息以 HTTP POST 的形式推送到回调地址，消息体格式大致如下：

json{
  "appId": "设备ID",
  "fromWxid": "发送方微信ID",
  "toWxid": "接收方微信ID",
  "type": 1,
  "content": "消息正文",
  "msgId": "消息唯一ID",
  "createTime": 1710000000
}

回调服务必须能被公网访问，且在 200ms 内返回 HTTP 200，否则平台会判定推送失败。

二、消息收发接口

消息模块是个人微信 API 最核心的能力，通常支持文字、图片、文件、语音、视频、链接卡片等多种消息类型。

2.1 发送消息接口一览

toWxid 填写好友的微信 ID 即为私聊，填写群的 chatroom ID（通常以 @chatroom 结尾）即为群发。

pythonAPPID = "你的appId"

# 发送文本消息
def send_text(to_wxid: str, content: str, ats: list = None):
    body = {
        "appId": APPID,
        "toWxid": to_wxid,
        "content": content,
    }
    if ats:
        body["ats"] = ",".join(ats)   # 群@成员的微信ID，逗号分隔
    resp = requests.post(f"{BASE}/message/postText", headers=HEADERS, json=body)
    return resp.json()

# 发送本地图片（先上传，再用转发接口避免重复上传）
def send_image(to_wxid: str, img_url: str):
    body = {"appId": APPID, "toWxid": to_wxid, "imgUrl": img_url}
    return requests.post(f"{BASE}/message/postImage", headers=HEADERS, json=body).json()

# 代码为示例，具体接口/字段以官方文档为准

2.2 转发接口与下载接口

当同一张图片/文件需要发给多个人时，先发一次取得平台内部的消息ID，再用转发接口批量转发，比每次重新上传效率高得多，也能降低被风控的概率。

下载接口（downloadImage、downloadFile）用于将回调中收到的媒体消息保存到本地。由于微信媒体链接有时效性，建议收到回调后立即异步下载，每条下载请求之间随机间隔 3～10 秒，避免短时集中请求触发频控。

三、好友管理接口

3.1 搜索与添加

添加好友是敏感操作，接口平台通常将其拆分为"搜索"和"发起添加"两步，并在频率上有明确限制。

频率建议（来自平台实践总结）：

• 每天主动加好友不超过 5～15 人，每 2 小时不超过 5 人，请求之间加随机延迟
• 新账号建议在线稳定 3 天以上再执行加好友操作
• 被动通过好友请求每天不超过 200 条
• 搜索操作每天控制在 10～20 次以内

python# 搜索用户
def search_user(keyword: str):
    body = {"appId": APPID, "keyword": keyword}   # 微信号或手机号
    return requests.post(f"{BASE}/contacts/search", headers=HEADERS, json=body).json()

# 发送好友申请
def add_friend(to_wxid: str, remark: str = "你好，我是XXX"):
    body = {"appId": APPID, "toWxid": to_wxid, "remark": remark}
    return requests.post(f"{BASE}/contacts/addContacts", headers=HEADERS, json=body).json()

# 代码为示例，具体接口/字段以官方文档为准

3.2 通讯录拉取

fetchContactsList 接口会返回当前账号所有好友的基础列表（微信ID、昵称），若需要头像、性别、地区等完整信息，再用 getDetailInfo 按需查询，避免一次性批量请求所有好友详情造成频控。

四、群聊管理接口

群聊接口是个人微信 API 中能力最丰富的模块之一，从建群、拉人、踢人到群公告、群二维码均有覆盖。

4.1 群操作接口汇总

python# 创建群聊
def create_chatroom(member_list: list):
    """
    member_list: 初始成员微信ID列表，至少2人，加上自己共3人起群
    """
    body = {"appId": APPID, "memberList": member_list}
    return requests.post(f"{BASE}/group/createChatroom", headers=HEADERS, json=body).json()

# 设置群公告
def set_announcement(chatroom_id: str, content: str):
    body = {"appId": APPID, "chatroomId": chatroom_id, "announcement": content}
    return requests.post(
        f"{BASE}/group/setChatroomAnnouncement", headers=HEADERS, json=body
    ).json()

# 获取群成员
def get_members(chatroom_id: str):
    body = {"appId": APPID, "chatroomId": chatroom_id}
    return requests.post(
        f"{BASE}/group/getChatroomMemberList", headers=HEADERS, json=body
    ).json()

# 代码为示例，具体接口/字段以官方文档为准

建群频率建议：每天新建群不超过 10 个，每次建群间隔 10 分钟以上；邀请成员时同样注意间隔，避免短时大量操作触发风控。

五、朋友圈接口

朋友圈接口相对较少，主要覆盖发帖和互动两类操作。

5.1 发布朋友圈

python# 发布文字朋友圈
def post_text_sns(content: str):
    body = {"appId": APPID, "content": content}
    return requests.post(f"{BASE}/sns/sendTextSns", headers=HEADERS, json=body).json()

# 发布图片朋友圈
def post_img_sns(content: str, img_urls: list):
    body = {"appId": APPID, "content": content, "imgUrls": img_urls}
    return requests.post(f"{BASE}/sns/sendImgSns", headers=HEADERS, json=body).json()

# 代码为示例，具体接口/字段以官方文档为准

5.2 朋友圈互动

likeSns 接口支持对指定动态点赞。新账号建议在线稳定 1 天后再操作朋友圈；获取好友动态每天不超过 200 条，点赞、评论之间随机间隔 5～20 秒，模拟人工节奏。

六、接入方式与调用框架

如果希望通过现成的 HTTP 服务直接调用上述能力，而不必自行维护协议层，WechatApi 提供扫码登录、消息收发、好友与群管理等 REST 接口，注册后即可 HTTP 调用，详见 WechatApi。

除托管服务外，也有开源方案（如 gewechat 等基于协议的框架），走自部署路线，需要自行维护服务器和账号风险，技术门槛相对更高。

通用错误排查

七、能力对比总览

下表将本文涉及的所有接口按模块汇总，方便快速检索：

实际对接时，能力范围以所选平台的官方文档为准，部分平台可能还提供转账记录读取、标签管理、消息撤回等扩展能力。

总结

个人微信 API 的核心能力可以归纳为五个方向：登录设备管理、消息收发、好友管理、群聊管理、朋友圈交互。理解每个模块的接口边界和频率约束，是构建稳定微信自动化服务的基础。在设计系统时，建议优先做好回调处理的异步解耦、媒体文件的队列下载以及操作频率的随机化，这三点是降低账号风险的关键所在。