微信好友关系检测接口（僵尸粉检测）

前言

微信生态中，长期运营的个人号往往积累大量"僵尸粉"——那些已将你删除、拉黑或注销的好友。这些无效联系人不仅占据通讯录空间，还会在群发、消息触达等场景造成虚报数据、浪费资源。传统手动逐一验证的方式费时费力，而批量调用微信好友关系检测接口则能自动识别双向好友状态，是私域流量精细化运营的必备基础能力。

什么是僵尸粉，为什么要批量检测

所谓"僵尸粉"，在微信场景下通常指以下几类账号：

1. 单向删除：对方已将你从好友列表删除，但你这边的通讯录仍显示该联系人。此时你可以向对方发消息，但消息实际上会以"待验证"或"对方不是你的好友"形式被拦截，或对方根本收不到。
2. 双向删除：双方均已解除好友关系，通讯录里的记录是历史残留。
3. 账号注销：对方的微信账号已注销，但通讯录条目仍存在。
4. 被拉黑：对方将你拉入黑名单，消息虽能发送但对方不可见，好友关系实质上已断裂。

对于运营数万用户的私域账号来说，定期做一次好友关系清洗，可以带来以下收益：

• 群发触达率提升：去掉无效账号后，群发到达率统计更准确，ROI评估更真实。
• 好友槽位释放：个人微信账号有好友上限，清理僵尸粉可释放槽位引入新用户。
• 降低封号风险：向大量无效账号发消息会触发微信风控，清洗后可降低异常行为评分。
• 精准用户画像：以真实活跃好友为基数，流失分析、留存模型才有意义。

人工一个个发"在吗"来测试的方法，在百人量级以下还勉强可行，一旦账号体量达到数千甚至万级，就必须依赖自动化的接口检测能力。

好友关系检测的核心原理

微信客户端本身存在一套好友状态同步机制。当你向一个已删除你的好友发起某些特定类型的请求（如获取用户名片、发送特定协议包），服务端会返回相应的状态码，标识该联系人与你的关系是否仍为双向好友。

基于 个人微信API 的实现方式，通过底层 微信iPad协议 模拟正常客户端行为发起好友状态探测请求，避免触发微信对 Web/PC 端异常访问的检测策略。其核心流程如下：

已登录的微信设备实例
        │
        ▼
向目标 wxid 发送好友状态查询协议包
        │
        ▼
微信服务端返回关系状态码
        │
   ┌────┴────┐
   ▼         ▼
双向好友    非好友/已删/拉黑/注销

iPad 协议层面的好友检测比直接发消息更轻量，且不会在对方设备上留下消息记录，对用户体验无干扰，同时可以批量并发执行。

值得注意的是，这类检测对账号本身有一定消耗，因此 WechatApi 在接口层面内置了频控策略，调用方无需自行实现冷却逻辑，只需关注返回的关系状态字段即可。

接口调用方式详解

WechatApi 采用统一的 HTTP POST + JSON 调用范式，鉴权通过请求头 VideosApi-token 传递，业务参数中 appId 为已登录微信设备的设备 ID。

请求示例

以下是一个 Python 调用示例，演示如何检测单个微信号的好友关系状态：

pythonimport requests

url = "https://api.wechatapi.net/v2/contact/check_friend"  # 示意路径，以实际文档为准

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

payload = {
    "appId": "your_device_appid",      # 已登录微信的设备ID
    "toWxId": "wxid_xxxxxxxxxxxxxxx"   # 待检测的微信号wxid
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

返回体结构

接口统一返回以下结构，data.friendStatus 是核心字段：

json{
  "ret": 200,
  "msg": "操作成功",
  "data": {
    "toWxId": "wxid_xxxxxxxxxxxxxxx",
    "friendStatus": 1,
    "statusDesc": "双向好友",
    "remark": "张三",
    "nickName": "张三的微信"
  }
}

friendStatus 取值说明见下节表格。

批量检测示例

生产场景下通常需要批量处理，以下是 bash 脚本示例，循环调用接口处理 wxid 列表：

bash#!/bin/bash

TOKEN="your_api_token_here"
APP_ID="your_device_appid"
WXID_FILE="wxid_list.txt"   # 每行一个 wxid

while IFS= read -r wxid; do
  echo "检测: $wxid"
  curl -s -X POST "https://api.wechatapi.net/v2/contact/check_friend" \
    -H "VideosApi-token: ${TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{\"appId\":\"${APP_ID}\",\"toWxId\":\"${wxid}\"}" | python3 -m json.tool
  sleep 0.5   # 适当间隔，遵守频控
done < "$WXID_FILE"

实际部署时建议将结果写入数据库或 CSV，并对 ret 非 200 的情况做重试和告警。

关键返回字段说明

friendStatus 枚举值：

实操建议：清洗流程设计

好友关系检测接口只是工具，围绕它设计一套合理的清洗流程才能真正落地：

第一步：导出全量通讯录 wxid

通过 WechatApi 提供的通讯录获取接口，拉取当前设备账号的全量好友列表，得到 wxid 数组。建议首次运行时全量拉取，后续增量同步。

第二步：分批检测好友状态

将 wxid 列表按每批 50-100 条分组，逐批调用检测接口。WechatApi 内置频控，不建议单批次过大或并发过高，以免触发微信后台的异常请求检测。

对于账号体量在 5000 人以下的场景，建议在业务低峰时段（凌晨 0-6 点）安排定时任务执行检测，单次完整扫描耗时通常在 1-2 小时内。

第三步：状态分级打标

将检测结果写入你的 CRM 或数据库，按 friendStatus 打标分级：

• 正常好友：继续日常运营；
• 单向删除（状态 2）：暂停消息触达，进入"流失预警"队列，可安排人工二次确认；
• 已注销/双删/拉黑（状态 3/4/5）：批量删除或归档，释放槽位。

第四步：定期复检与增量更新

好友关系并非一次性检测即可，用户随时可能删除你或重新加回。建议每 30 天对全量好友做一次复检，对新增好友在添加后 7 天做一次状态确认。

这套流程可以无缝集成到 微信SCRM 体系中，与用户标签、互动记录联动，实现真正意义上的私域用户全生命周期管理。

注意事项与合规使用

使用好友关系检测接口时，有几点需要特别关注：

频率控制

WechatApi 在协议层面已做了频控保护，但调用方仍应在应用层设置合理的请求间隔。单个设备账号每分钟检测请求建议不超过 120 次，日均检测量根据账号体量和风险策略灵活配置。如果你同时管理多个账号，可以通过多个 appId 分散检测压力。

账号安全

检测本身属于正常客户端行为的模拟，但如果短时间内对大量不活跃账号密集发起请求，仍可能触发微信的异常行为检测。建议：

• 检测任务分散到非业务高峰时段；
• 单次批量任务规模不超过账号好友总数的 20%；
• 发现账号出现异常提示时立即暂停检测，联系 WechatApi 技术支持排查。

结果时效性

检测结果存在时效性，建议在数据库中记录检测时间戳（checkedAt），避免使用超过 30 天的旧检测结果做决策。

数据隐私

好友关系检测获取到的用户信息（昵称、备注等）属于个人数据，应按照合规要求妥善存储和使用，不得将数据用于接口服务允许范围之外的场景。

与其他接口的联动

好友关系检测通常不会单独使用，而是作为更大业务流程的一环。以下是几个典型联动场景：

场景一：清洗后自动删除 检测到状态 3/4/5 的账号后，调用好友删除接口自动清理，无需人工操作。适合通讯录规模大、运营人员有限的团队。

场景二：流失预警与召回 检测到状态 2（对方删除我）时，触发"流失预警"工作流，自动记录删除时间，并在运营系统中标记为流失用户，供后续分析流失原因。

场景三：新用户入库前核验 在用户加微信好友后，延迟 24 小时调用检测接口确认好友状态，避免将"加了又删"的无效用户写入正式用户库。

场景四：群成员真实关系核查 结合 WechatApi 的微信群成员列表接口，对群成员逐一检测好友关系，识别出群内非好友成员，为精细化群运营提供数据支撑。详细的群管理能力可参考 微信群管理机器人 的产品文档。

如果你的业务涉及多账号协同、自动化客服响应等更复杂的场景，可以将好友关系检测结合 微信二次开发 能力统一编排，构建完整的私域用户管理中台。

小结

微信好友关系检测接口（僵尸粉检测）是私域流量运营中容易被忽视、却极具实用价值的基础能力。通过 WechatApi 提供的 iPad 协议层好友状态探测接口，开发者可以以低侵入、高准确率的方式批量识别无效联系人，结合清洗流程和 SCRM 系统实现通讯录的持续健康管理。

核心要点回顾：

• 检测接口返回 friendStatus 字段区分双向好友、单向删除、注销、拉黑等五种状态；
• HTTP POST + VideosApi-token 鉴权，appId 指定设备实例，调用范式统一；
• 建议分批检测、低峰执行、结果落库打标，配合 30 天复检周期；
• 检测能力可与群管理、SCRM、客服机器人等模块联动，构建完整私域运营闭环。

如需接入试用或了解更多接口细节，可访问 WechatApi 官网 注册账号，查阅开发文档获取完整的接口规范和错误码说明。