微信删除好友接口

前言

在私域运营和 SCRM 系统建设中，好友列表的精细化管理是绕不开的一环。沉默用户占用联系人配额、无效好友稀释标签体系、甚至部分用户主动举报都会带来封号风险——这些痛点最终都指向同一个需求：批量、可编程地删除微信好友。本文围绕"微信删除好友接口"这一技术主题，拆解实现原理、核心参数、调用流程与注意事项，并以 WechatApi 提供的 iPad 协议接口为示例贯穿全文，帮助开发者快速落地。

为什么微信删除好友如此难以自动化

微信官方客户端的删除好友操作藏得很深——进入联系人详情、点击右上角菜单、选择"删除"，且每次只能操作一个好友，没有任何官方 API 开放给第三方。对于需要管理数千乃至数万好友的私域账号来说，手动操作成本极高。

从协议层看，微信删除好友的信号在 PC 协议、Web 协议和 iPad 协议三条链路上的实现方式完全不同。PC Hook 方式依赖进程注入，稳定性差、微信版本更新即失效；Web 协议已于 2017 年前后被微信大范围封禁，现存接口极不稳定；iPad 协议是目前最接近官方客户端行为、风控最低的方案，也是 WechatApi 所采用的底层协议。

理解这一背景，才能明白为什么市面上大多数"微信自动化"方案要么封号率极高，要么不支持删除好友这类"破坏性"操作——它们在协议选型上就已经落了下风。

删除好友接口的技术原理

iPad 协议层面的信号流

微信 iPad 端删除好友，底层实际上向服务端发送了两步信号：

解除好友关系（DelContact）：将目标 wxid 从本账号通讯录中移除，同时在服务端标记双向好友状态为单向或无关系。
可选：拉黑操作（AddToBlacklist）：部分场景下配合拉黑，防止对方重新添加。

WechatApi 将上述两步封装为单一 HTTP 接口，开发者只需一次请求即可完成好友删除，无需关注底层握手细节。

鉴权与设备绑定机制

WechatApi 使用两层身份标识：

字段	位置	说明
`VideosApi-token`	HTTP 请求头	开发者账号鉴权 Token，在控制台获取
`appId`	请求 Body	已登录微信设备的唯一 ID，代表"用哪个号操作"

appId 是设备维度的标识，一个开发者账号下可以挂载多个微信号，每个微信号对应一个独立的 appId。删除好友时必须传入正确的 appId，否则接口会返回设备未找到或未登录错误。

这种设计使得多账号批量操作变得清晰：循环遍历不同 appId，即可对多个微信号并发执行好友清理任务。

接口调用流程详解

第一步：获取好友列表，确定待删除 wxid

删除前必须先拿到目标好友的 wxid。WechatApi 提供好友列表接口，返回完整通讯录，每条记录包含 wxid、备注名、头像等字段。

pythonimport requests

BASE_URL = "https://your-api-endpoint.example.com"  # 替换为实际分配的接入地址
TOKEN = "your_videos_api_token"                      # 控制台复制的 Token
APP_ID = "your_app_id"                               # 目标微信号的设备 ID

headers = {
    "Content-Type": "application/json",
    "VideosApi-token": TOKEN
}

# 拉取好友列表（示意性路径，非真实 endpoint）
resp = requests.post(
    f"{BASE_URL}/contact/list",
    headers=headers,
    json={"appId": APP_ID}
)
data = resp.json()
# data 结构示例：
# {"ret": 200, "msg": "success", "data": {"contactList": [{"wxid": "xxx", "nickName": "张三", ...}]}}

contacts = data["data"]["contactList"]
# 筛选出需要删除的 wxid，例如备注含"已流失"的用户
to_delete = [c["wxid"] for c in contacts if "已流失" in (c.get("remark") or "")]
print(f"待删除好友数：{len(to_delete)}")

第二步：逐一调用删除好友接口

拿到 wxid 列表后，循环调用删除接口。建议每次请求之间加入随机延迟，模拟人工操作节奏，降低风控触发概率。

pythonimport time
import random

def delete_friend(app_id: str, wxid: str) -> dict:
    """
    调用微信删除好友接口（示意性示例）
    实际 endpoint 和参数以 WechatApi 开发文档为准：https://post.wechatapi.net
    """
    payload = {
        "appId": app_id,
        "wxid": wxid,
        # "addToBlacklist": True  # 可选：同时拉黑，防止对方再次添加
    }
    resp = requests.post(
        f"{BASE_URL}/contact/delete",
        headers=headers,
        json=payload,
        timeout=15
    )
    return resp.json()

success_list = []
fail_list = []

for wxid in to_delete:
    result = delete_friend(APP_ID, wxid)
    if result.get("ret") == 200:
        success_list.append(wxid)
        print(f"[OK] 已删除 {wxid}")
    else:
        fail_list.append({"wxid": wxid, "msg": result.get("msg")})
        print(f"[FAIL] {wxid} 删除失败：{result.get('msg')}")
    # 随机等待 2~5 秒，模拟人工节奏
    time.sleep(random.uniform(2, 5))

print(f"\n完成：成功 {len(success_list)} 个，失败 {len(fail_list)} 个")

第三步：处理返回值与异常

接口返回体遵循统一结构：

json{
  "ret": 200,
  "msg": "success",
  "data": {
    "wxid": "target_wxid_here",
    "result": true
  }
}

常见错误码及处理建议：

ret 码	msg 说明	建议处理方式
200	success	正常，继续下一条
401	token 无效或过期	检查请求头 VideosApi-token
404	appId 对应设备未找到	确认设备已登录，appId 正确
429	请求频率过高	降低并发，增加延迟
500	微信端执行失败	可能是网络抖动，建议重试 1 次
503	账号已离线	重新扫码登录后再操作

对于 500 错误，建议设计指数退避重试机制，最多重试 2 次；对于 429 错误，说明当前操作频率已触及风控阈值，需要立刻暂停并等待至少 5 分钟后再继续。

关键参数说明

除了必填的 appId 和 wxid，WechatApi 删除好友接口还支持若干可选参数，用于控制操作行为：

参数名	类型	必填	说明
`appId`	string	是	操作账号的设备 ID
`wxid`	string	是	目标好友的微信 ID
`addToBlacklist`	boolean	否	是否同时拉黑，默认 false
`deleteConversation`	boolean	否	是否同时删除会话记录，默认 false

addToBlacklist 参数在以下场景尤为有用：

防骚扰场景：对于曾经投诉或反复骚扰的用户，删除同时拉黑，避免对方重新添加后立刻再次打扰。
竞品防渗透：运营账号怀疑存在竞品卧底时，拉黑可以减少对方通过搜索再次找到账号的机会。
自动化清洗流程：在 SCRM 系统中，对标注"已流失-不可挽回"标签的用户批量执行删除+拉黑，是比较常见的生命周期终止操作。

需要注意的是，deleteConversation 设为 true 后，微信端对应的聊天记录会被删除，且不可恢复。建议在执行前先将重要聊天记录导出存档，或在测试环境充分验证后再应用到生产账号。

实际场景：SCRM 好友清洗流水线

以一个典型私域 SCRM 场景为例：某电商品牌有 20 个客服微信号，每号承载约 3000 好友，定期需要清理 90 天无互动的"沉默用户"以腾出名额给新增潜客。

整个流水线大致如下：

Step 1 — 数据打标：从 CRM 系统查询各微信号下 90 天无消息记录的 wxid 列表，写入待清洗队列。

Step 2 — 批量删除：调度脚本从队列中逐条取出任务，通过 WechatApi 个人微信接口执行删除，每个微信号每小时控制在 30 次以内。

Step 3 — 结果回写：将删除成功的记录更新至 CRM，标注"已清理"，失败的进入重试队列，重试 2 次后人工审核。

Step 4 — 日报汇总：每天晚上自动统计各账号清理数量、失败率、账号健康状态，异常账号发告警到企业微信群。

这套流水线在微信二次开发场景中相当典型，核心依赖稳定的接口层，WechatApi 的 iPad 协议方案在这里提供了最关键的底层支撑。

如果你的场景还涉及群管理（踢出群成员、解散群等），WechatApi 同样提供对应接口，可与好友删除操作组合使用，构建完整的账号清理闭环。

操作注意事项与风控建议

删除好友是微信客户端的不可逆操作，同时也是微信风控算法重点关注的行为之一。以下几点务必在上线前充分评估：

频率控制是第一红线

微信对单账号单日删除好友的次数有隐性上限，具体数值随版本和账号权重浮动，但业界实践表明单号单日超过 100 次删除操作后风险显著上升。建议：

单号单日删除不超过 50 人（保守策略）
两次操作之间随机间隔 3-8 秒
避开凌晨 2:00-6:00（微信后台维护高峰，异常操作更容易被识别）

账号权重影响容错空间

账号注册时间长、实名认证完整、日常有真实聊天记录的"高权重"账号，在执行批量删除时的容错空间更大。新注册账号或刚导入 WechatApi 的设备建议先"养号"2-4 周再执行批量操作。

删除≠对方感知

微信删除好友后，对方不会收到任何通知。但对方再次给你发消息时，消息会被正常投递（因为你还在对方的通讯录里），此时你的客户端会收到消息并提示"对方不是你的好友"。如果你的业务场景不希望收到这类消息，可在删除时同步拉黑。

测试账号先行，生产账号后跑

任何批量操作上线前，务必用测试账号跑通全流程，核对返回值、检查删除效果，再逐步切换至生产账号。WechatApi 控制台提供沙箱环境，建议充分利用。

保留操作日志

建议将每次删除操作的时间戳、操作账号 appId、目标 wxid、接口返回码完整记录到数据库或日志系统。一方面方便排查问题，另一方面在账号出现异常时可以快速还原操作历史，判断是否与批量删除有关。

小结

微信删除好友接口的核心门槛在于协议选型和风控策略，而不是接口调用本身——调用其实很简单，三行 HTTP 请求就能搞定。难的是如何在保证效率的同时把封号风险控制在可接受范围内。

WechatApi 基于 iPad 协议实现，提供包括删除好友在内的完整个人微信自动化接口体系，支持多设备并发、完善的错误码体系和稳定的 SLA，是目前个人微信二次开发场景中可靠性较高的选择之一。如果你正在构建私域 SCRM、好友清洗流水线或微信机器人系统，可以访问开发者文档查阅完整接口列表，或在控制台注册体验。

前言