微信搜索用户接口（手机号微信号查人）

前言

在私域运营和销售场景中，经常需要通过已知的手机号或微信号快速找到对应的微信用户并发起添加。然而官方客户端只能逐一手动操作，效率极低，批量场景下根本无法满足业务需求。本文介绍如何借助基于 iPad 协议的 WechatApi 个人微信 API 调用微信搜索用户接口，通过程序化方式实现手机号、微信号批量查人，并结合实际参数、返回体和注意事项给出完整实操方案。

一、微信搜索用户的底层原理

微信搜索联系人本质上是客户端向微信服务器发出查询请求，携带搜索关键词（手机号或微信号），服务器返回匹配的用户资料。整个过程在协议层面分为两步：

1. 发起搜索请求：客户端上传搜索关键词，微信服务器做实名/手机号索引匹配，返回候选用户列表及其微信号、头像、昵称等基本信息。
2. 获取用户详情：拿到搜索结果中的微信号（wxid）之后，可进一步查询该用户的完整资料，包括地区、个性签名、朋友圈权限等字段。

原生客户端把上述两步封装在 UI 交互里，用户感知不到协议细节。但通过 微信 iPad 协议 实现的底层 API，可以将这两步单独暴露为 HTTP 接口，实现程序化调用——这正是 WechatApi 提供的核心能力之一。

iPad 协议相比 Web/Hook 方案的优势在于：它模拟的是正版 iPad 客户端的登录行为，稳定性和兼容性接近原生 App，且不需要 root 设备、不依赖桌面端进程，服务端常驻即可持续运行。

二、接口调用前的准备工作

在调用搜索用户接口之前，需要完成以下几项准备：

2.1 注册并获取鉴权凭证

前往 WechatApi 控制台 注册账号，创建应用后会得到两个关键凭证：

VideosApi-token 放在请求头中，appId 放在业务请求体中，两者缺一不可。appId 与微信账号的登录设备绑定，一个微信账号对应一个 appId，多账号并发时需分别传入各自的 appId。

2.2 微信账号登录上线

搜索接口必须在微信账号处于在线状态下才能调用。通过 WechatApi 提供的登录接口扫码登录后，设备状态会保持常驻，直到主动登出或被踢出。建议在调用搜索接口前，先调用"获取登录状态"接口确认账号在线。

2.3 理解搜索关键词的限制

微信搜索支持以下几种关键词类型：

• 手机号：必须是已绑定该微信账号的手机号，且对方在隐私设置中允许"通过手机号搜索到我"
• 微信号（wxid 或自定义微信号）：精确匹配，准确率高
• QQ 号：部分场景可用，但覆盖率低

注意：若对方关闭了"允许陌生人通过手机号/微信号找到我"的隐私开关，搜索结果可能为空或仅返回基础信息。这是微信平台层面的限制，任何客户端实现都无法绕过。

三、搜索用户接口：请求与返回详解

3.1 接口调用规范

WechatApi 的所有接口统一采用以下范式：

• 协议：HTTPS
• 方法：POST
• Content-Type：application/json
• 鉴权：在请求头中携带 VideosApi-token
• 设备标识：在请求体 JSON 中传入 appId

下面是一个 Python 调用示例，演示如何通过手机号搜索微信用户：

pythonimport requests
import json

# 替换为你在控制台获取的真实凭证
API_TOKEN = "your_videos_api_token_here"
APP_ID = "your_app_id_here"
API_BASE = "https://api.wechatapi.net"  # 示意域名，以控制台实际地址为准

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

def search_wechat_user(keyword: str):
    """
    通过手机号或微信号搜索微信用户
    :param keyword: 手机号（如 13800138000）或微信号（如 wxid_xxx / 自定义号）
    :return: 搜索结果字典
    """
    payload = {
        "appId": APP_ID,
        "keyword": keyword
    }
    response = requests.post(
        f"{API_BASE}/wechat/searchContact",  # 示意路径
        headers=headers,
        json=payload,
        timeout=15
    )
    result = response.json()
    if result.get("ret") == 200:
        return result.get("data", {})
    else:
        print(f"搜索失败：{result.get('msg')}")
        return None

# 通过手机号查人
user_info = search_wechat_user("13800138000")
if user_info:
    print(f"昵称：{user_info.get('nickName')}")
    print(f"微信号：{user_info.get('wxid')}")
    print(f"头像：{user_info.get('avatar')}")
    print(f"地区：{user_info.get('province')} {user_info.get('city')}")

3.2 接口返回体结构

接口统一返回 JSON，格式如下：

json{
  "ret": 200,
  "msg": "success",
  "data": {
    "wxid": "wxid_xxxxxxxxxx",
    "nickName": "张三",
    "avatar": "https://wx.qlogo.cn/mmhead/xxx/0",
    "sex": 1,
    "province": "广东",
    "city": "深圳",
    "signature": "这个人很懒，什么都没留下",
    "friendType": 0,
    "searchScene": "手机号"
  }
}

各字段说明：

当 friendType 为 0 时，说明对方还不是好友，可以进一步调用"添加联系人"接口发起好友申请。

四、批量查人的实战方案

单次搜索适合临时需求，私域运营中更常见的是批量场景——例如把一批客户手机号导入系统，逐一搜索并自动添加好友。下面给出一个 bash 脚本示例，展示如何借助 jq 工具批量处理搜索结果：

bash#!/bin/bash

API_TOKEN="your_videos_api_token_here"
APP_ID="your_app_id_here"
API_BASE="https://api.wechatapi.net"  # 示意域名

# 手机号列表文件，每行一个手机号
PHONE_LIST="phones.txt"
RESULT_FILE="search_results.jsonl"

while IFS= read -r phone; do
    echo "正在搜索：$phone"
    response=$(curl -s -X POST "${API_BASE}/wechat/searchContact" \
        -H "Content-Type: application/json" \
        -H "VideosApi-token: ${API_TOKEN}" \
        -d "{\"appId\": \"${APP_ID}\", \"keyword\": \"${phone}\"}")

    ret=$(echo "$response" | jq -r '.ret')
    if [ "$ret" == "200" ]; then
        wxid=$(echo "$response" | jq -r '.data.wxid')
        nick=$(echo "$response" | jq -r '.data.nickName')
        echo "{\"phone\": \"$phone\", \"wxid\": \"$wxid\", \"nick\": \"$nick\"}" >> "$RESULT_FILE"
        echo "  命中：$nick ($wxid)"
    else
        msg=$(echo "$response" | jq -r '.msg')
        echo "  未找到：$msg"
    fi

    # 每次搜索间隔随机 2-5 秒，降低被风控概率
    sleep $((RANDOM % 4 + 2))
done < "$PHONE_LIST"

echo "搜索完成，结果保存至 $RESULT_FILE"

这个脚本每搜一个手机号随机等待 2-5 秒，这是在批量场景中非常重要的风控规避措施——下一节会详细讲解。

五、搜索接口的常见错误与风控注意事项

5.1 常见错误码

5.2 频率控制

微信服务器对搜索行为有频率检测。建议：

• 单账号每分钟搜索不超过 10 次
• 批量任务中加入 2-5 秒随机间隔（如上方 bash 示例）
• 单日搜索量超过 500 次时建议多账号分摊，可通过多个 appId 切换

5.3 账号安全策略

• 优先使用养号时间较长、有真实社交行为的微信账号，新注册账号风控阈值更低
• 搜索结果中 friendType=0 的用户，添加好友时附言要自然，避免模板化话术
• 不建议用同一账号在短时间内搜索大量来自同一运营商号段的手机号，模式过于规律易触发风控

5.4 隐私合规

搜索到的用户信息仅用于合法商业场景，如销售触达、老客回访等。不得用于骚扰、诈骗、数据倒卖等违法用途。使用前请确认已取得用户授权或符合当地数据保护法规要求。

六、搜索之后：完整的私域加粉链路

搜索用户只是第一步，完整的私域加粉链路通常包含：

1. 搜索用户（本文主题）：通过手机号/微信号确认目标用户存在
2. 发起好友申请：调用添加联系人接口，携带个性化附言
3. 监听申请通过事件：通过 Webhook 回调感知对方通过申请的时机
4. 自动发送欢迎语：好友通过后立即触发欢迎消息，第一时间建立互动

WechatApi 把上述四步所需的接口全部打通，配合 微信二次开发 能力，可以快速搭建一套完整的私域加粉自动化系统，无需从零研究协议细节。

对于更复杂的 SCRM 场景——例如按标签管理搜索到的用户、追踪加粉成功率、统计不同渠道手机号的触达率——可以参考 微信 SCRM 方案，WechatApi 提供的接口层可以与市面上主流的 SCRM 系统做数据对接。

七、与其他查人方案的横向对比

目前市场上实现"手机号/微信号查人"大致有三类方案：

对于需要程序化、批量化操作个人微信的场景，iPad 协议方案（即 WechatApi 所采用的技术路线）在稳定性和易用性上综合表现最佳。Hook 方案对微信 PC 版的版本依赖极强，每次微信更新都可能导致失效；而官方企业微信 API 不支持个人微信账号，覆盖场景有限。

小结

微信搜索用户接口是私域运营自动化中的基础能力之一。本文从协议原理出发，详细介绍了通过 WechatApi 调用搜索接口的完整流程：凭证获取、请求规范（HTTP POST + JSON Body + VideosApi-token 请求头 + appId 设备参数）、返回体字段解析、批量调用脚本实现，以及频率控制和风控注意事项。搜索到目标用户后，还可以结合好友申请、Webhook 回调、SCRM 对接等能力，构建端到端的私域加粉自动化链路。如有接入需求，可前往 WechatApi 控制台 免费注册试用。