WhatsApp 号码查询 API：校验与补全手机号数据

发布于 2026年8月23日 · 更新于2026年10月9日

WhatsApp 号码查询 API 能把一个原始手机号变成结构化数据：这个号码在 WhatsApp 上吗？如果在，它的公开资料显示了什么——头像、「关于」签名、企业信息，还是在线信号？你不必围着客户端搭建脆弱的自动化流程，只要调用一个 HTTP 接口，就能拿到 JSON 结果。

本文介绍「WhatsApp 号码校验与资料查询」项目里的各个接口、把它们串起来的 userHash 两段式流程，以及如何用 Python 调用而不浪费点数。

API 能做什么

这个项目围绕一个目标来组织接口，就是了解一个号码：

  • 注册校验：check-exist-by-phone、check-exist-by-cc-phone 和 check-active 告诉你号码是否有可用的 WhatsApp 账号。
  • 资料数据：get-avatar 和 get-about 返回头像与「关于」文本。
  • 在线状态：get-presence 返回在线或最后在线信号，受对方隐私设置的限制。
  • 企业资料：get-biz-profile 返回 WhatsApp 企业账号的商家信息。
  • 批量校验：batch-check-10 一次请求最多校验 10 个号码。
  • 稀疏的附加信息：get-device-name、get-email 和 get-wa-old-device-name 仅在校验结果表明存在时才可用。

第一步：获取 API Key

注册后打开控制台，复制一个有效的 API Key。新账户赠送免费点数，可以马上开始试验。

第二步：校验号码

check-exist-by-phone 是针对单个号码的轻量存在性检查，比完整的资料查询便宜。传入完整的国际号码即可：带不带 +、有没有空格或连字符、用不用 00 前缀都可以，接口会自动解析国家区号。

curl "https://api.opendata-api.com/api/project/whatsapp/check-exist-by-phone?key=YOUR_API_KEY&phoneNumber=15551234567"

结果字段 isExist 是三态值：true、false 或 null。null 表示结果不确定，正确的做法是稍后退避重试，而不是把号码标成未注册。isExist 为 true 时，响应还会包含：

  • userHash：用来授权下面几个较重查询的标识，有效期 24 小时。
  • hasExtra：这个号码有哪些补充字段。已注册号码一定有头像和签名；deviceName、email 和 waOldDeviceName 只在已知时才出现。

如果你本来就把国家区号和本地号码分开存储，check-exist-by-cc-phone 把它们作为 cc（不带 + 的拨号前缀，1 到 4 位）和 phone（本地号码，6 到 15 位，不带前导零）两个参数。如果只需要快速得到是或否，并且不打算做补全，check-active 对完整的国际号码直接返回一个活跃标志，不需要 userHash。

第三步：用资料数据补全

传入上一步得到的 userHash。号码本身由服务端解析，所以这些接口不接受电话号码参数，无效或过期的 hash 会被拒绝。

curl "https://api.opendata-api.com/api/project/whatsapp/get-avatar?key=YOUR_API_KEY&userHash=USER_HASH"
curl "https://api.opendata-api.com/api/project/whatsapp/get-about?key=YOUR_API_KEY&userHash=USER_HASH"
curl "https://api.opendata-api.com/api/project/whatsapp/get-biz-profile?key=YOUR_API_KEY&userHash=USER_HASH"

每个接口分别返回什么，以及空结果意味着什么：

  • get-avatar：pictureSet=true 时返回临时的照片链接，以及头像变化时会跟着变化的版本 ID。pictureSet=false 表示用户没有头像或隐藏了头像，reason 会说明原因。
  • get-about：返回「关于」文本和头像版本 ID。about 为空表示没有签名文本，或者对方隐藏了它。
  • get-biz-profile：商家名称、认证等级、简介、地址、邮箱、网站和入驻时间。个人号码会返回 isBusiness=false。
  • get-presence：在线状态或最后在线时间。如果对方不是你的联系人，并且隐私设置不是「所有人」，就不会返回在线信息，此时 visible=false。这是真实的结果，无法绕过。单次调用最长可能需要约 17 秒，所以只在确实需要时才调用。

在做依赖这些字段的功能之前，请先阅读WhatsApp 头像、签名与在线状态能拿到什么。

不浪费点数的 Python 示例

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.opendata-api.com/api/project/whatsapp"


def get(operation, **params):
    params["key"] = API_KEY
    resp = requests.get(f"{BASE}/{operation}", params=params, timeout=60)
    resp.raise_for_status()
    body = resp.json()
    # A reply can be wrapped more than once as {"code": ..., "data": {...}}
    while isinstance(body, dict) and "code" in body and isinstance(body.get("data"), (dict, list)):
        body = body["data"]
    return body


def whatsapp_profile(number):
    found = get("check-exist-by-phone", phoneNumber=number)
    exists = found.get("isExist")
    if exists is None:
        return {"number": number, "status": "retry"}
    if not exists:
        return {"number": number, "status": "not_on_whatsapp"}

    user_hash = found.get("userHash")
    if not user_hash:
        raise RuntimeError(f"no userHash in reply: {found}")
    avatar = get("get-avatar", userHash=user_hash)
    about = get("get-about", userHash=user_hash)
    business = get("get-biz-profile", userHash=user_hash)
    return {
        "number": number,
        "status": "registered",
        "has_photo": bool(avatar.get("pictureSet")),
        "about": about.get("about") or None,
        "is_business": bool(business.get("isBusiness")),
        "extras": found.get("hasExtra"),
    }


print(whatsapp_profile("15551234567"))

只有已注册的号码才会走到资料查询那一步，校验结果不确定的号码会被标记为待重试，而不是被丢弃。

我该用哪个接口？

目标接口
在注册表单里校验单个号码check-exist-by-phone 或 check-active
一次校验一小批号码batch-check-10
清洗大型名单每 10 个一批，见批量校验指南
展示头像或「关于」文本check-exist-by-phone，再调 get-avatar / get-about
识别企业账号get-biz-profile，或 batch-check-10（同时报告是否为企业账号）

如果你还在几个通讯工具之间做选择，WhatsApp 与 Telegram 查询对比会比较两者各自能返回什么。单个号码的基础步骤，请看如何检测号码是否在用 WhatsApp。

应用场景

  • 线索资格审查：在线索分配给销售之前先校验并补全。
  • 名单清洗：让 CRM 联系人只保留 WhatsApp 可触达的号码。
  • 注册引导：在切换到 WhatsApp 渠道前，确认用户能收到消息。
  • 数据研究与补全：规模化地为已知号码补充公开资料。

最佳实践

  • 先校验，再补全。 没通过注册校验的号码，跳过资料查询。
  • null 当作重试。 不确定的结果只是暂时性的。
  • 缓存校验结果。 保存 isExist、userHash 和时间戳，24 小时内直接复用 hash，不要重复校验。
  • 不要承诺字段一定有。 头像、签名和在线状态取决于每个人自己的隐私设置。
  • 保持合规。 只处理你有合法依据使用的号码，并遵守 WhatsApp 的条款。

常见问题

userHash 是什么，为什么需要它？ 它是注册校验针对已注册号码返回的标识。头像、签名、企业资料、在线状态以及附加信息这些资料接口，都需要它来授权较重的查询，有效期 24 小时。

isExist 返回 null 是什么意思？ 说明结果不确定，比如出现了临时性的故障。请稍后退避重试，不要把它当作「没有 WhatsApp」。

怎么判断一个号码是不是 WhatsApp 企业账号？ 用 userHash 调用 get-biz-profile，个人号码会返回 isBusiness=false。如果要一次判断很多号码，batch-check-10 会为每个号码同时报告注册状态和是否为企业账号。

使用这些查询需要我自己有 WhatsApp 账号吗？ 不需要。这些接口只要 API Key，加上号码或 userHash，你不需要创建会话，也不用绑定账号。发送消息是另一套流程，那套流程才需要会话。

为什么「关于」文本是空的？ 空值表示对方没有设置签名文本，或者隐藏了它。这是正常的结果，不是错误。

立即开始

在 WhatsApp 号码校验页面直接在线体验，阅读 check-exist-by-phone 与 get-avatar 接口文档，准备超出免费点数时再查看定价。