如何用 API 获取 WhatsApp 头像、简介与在线状态

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

一个已注册的 WhatsApp 号码往往带有公开足迹：头像、「关于」签名，以及在线或最后在线这类在线信号。对线索补全、身份核对和数据研究来说，这些公开资料很有价值，而且可以通过程序来获取。

本文介绍如何拉取号码的头像、签名、在线状态和企业资料，每种结果代表什么意思，以及同样重要的一点：哪些字段会返回为空，原因是什么。

两段式流程

资料查询以注册校验为前提。这样成本更低：先确认号码存在，再只为真实账号支付补全点数。

  1. 用 check-exist-by-phone 做注册校验。对已注册号码（isExist=true），它会返回有效期 24 小时的 userHash，以及说明可用补充字段的摘要 hasExtra。
  2. 把 userHash 传给各个资料接口，获取资料数据。号码由服务端解析，所以这些接口不接受电话号码参数，缺失、未知或已过期的 hash 都会被拒绝。
curl "https://api.opendata-api.com/api/project/whatsapp/check-exist-by-phone?key=YOUR_API_KEY&phoneNumber=15551234567"

从响应中复制 userHash。如果想完整了解校验本身，请阅读 WhatsApp 号码查询指南。

第二步：获取资料字段

头像：

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

pictureSet=true 时，响应包含一个临时的照片链接，以及一个在对方更换头像时就会变化的头像版本 ID。如果号码已注册但没有头像，或者通过隐私设置隐藏了头像，你会得到 pictureSet=false 和一个 reason。

简介 / 签名：

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

返回「关于」文本和头像版本 ID。about 为空表示对方没有设置签名文本，或者隐藏了它。

企业资料：

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

对 WhatsApp 企业账号，你会得到商家名称、认证等级、简介、地址、邮箱、网站和入驻时间。个人号码返回 isBusiness=false。

在线状态 / 最后在线：

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

在线状态受对方隐私设置的强烈约束。如果你不是对方的联系人，并且对方的最后在线或在线状态没有设为「所有人」，就拿不到在线信息，结果是 visible=false。这是真实的答案，无法绕过。单次调用可能需要约 17 秒，所以请把超时时间设得宽松一些，并且只在值得等待时才调用。

可选的附加信息

当校验结果在 hasExtra 里提示还有更多字段时，还有另外三个接口：get-device-name（机主的显示名称，通常只对当前活跃的账号可用）、get-email（经过掩码处理的备份邮箱，不是企业联系邮箱）和 get-wa-old-device-name（上一台设备的名称）。只有 hasExtra 里列出了某个字段，才去调用对应接口。字段不存在时，值为 null，message 会说明原因。

Python 示例

import requests

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


def get(operation, timeout=30, **params):
    params["key"] = API_KEY
    resp = requests.get(f"{BASE}/{operation}", params=params, timeout=timeout)
    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 enrich(number, with_presence=False):
    found = get("check-exist-by-phone", phoneNumber=number)
    if found.get("isExist") is not True:
        return {"number": number, "registered": found.get("isExist")}

    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)
    profile = {
        "number": number,
        "registered": True,
        "photo_set": bool(avatar.get("pictureSet")),
        "photo_reason": avatar.get("reason"),
        "about": about.get("about") or None,
    }
    if avatar.get("pictureSet") and avatar.get("url"):
        profile["photo_bytes"] = requests.get(avatar["url"], timeout=30).content
    if with_presence:
        presence = get("get-presence", timeout=60, userHash=user_hash)
        profile["presence_visible"] = presence.get("visible")
    return profile


print(enrich("15551234567"))

照片链接是临时的，所以代码会立即下载图片。如果之后还需要用，请自己保存这些字节。

检测资料变化

get-about 会以 pictureId 返回头像版本 ID，对方更换头像时它会跟着变化（get-avatar 也会报告头像版本 ID）。请把它和联系人一起保存。下次补全时，如果值不同，说明对方更新了头像，需要重新下载图片；如果值相同，就可以跳过下载。这样做定期刷新时，不必每次都重新获取所有图片，成本很低。

应用场景

  • 线索补全：销售外联前，为入站线索补上一张脸和更多上下文。
  • 身份信号：真实的头像和签名有助于区分真实账号和一次性账号，但两者都不能证明一个人到底是谁。
  • 活跃度提示：在线状态可见时，能提示联系人的活跃程度。很多人会把它隐藏起来，所以不要把它当作必需项。
  • 企业发现：对 WhatsApp 企业号码，用企业资料获取公司信息。

最佳实践

  • 务必先校验。 没通过注册校验的号码，不要调用资料接口。
  • userHash 最长缓存 24 小时，重复补全时不必重复校验。
  • 优雅处理空字段。 因隐私而隐藏是正常的，不是错误：pictureSet=false、about 为空和 visible=false 都是有效答案。
  • 立即下载头像。 照片链接是临时的。
  • 把资料数据当作个人信息对待。 只处理你有合法依据使用的号码，遵循数据最小化原则，并遵守 WhatsApp 的条款。

与 Telegram 的对比

Telegram 的资料查询返回简介和 base64 编码的头像，而且可以从用户名而不是号码开始查。如果需要把两个平台放在一起比较，请阅读 WhatsApp 与 Telegram 号码查询对比和 Telegram 号码检测。想把资料信号与其他检测结合进同一个评分流程，请看线索核验工作流。

常见问题

能否总是通过手机号拿到 WhatsApp 头像？ 不能。号码必须已注册，并且对方没有通过隐私设置隐藏头像。否则结果是 pictureSet=false 加上原因，这是正常的答案。

为什么 get-presence 返回 visible=false？ 只有你是对方的联系人，或者对方允许所有人查看最后在线或在线状态，你才能拿到在线信息。被隐藏时，接口会如实返回 visible=false，无法绕过。

怎么知道头像有没有更换？ get-about 会返回 pictureId，对方更换头像时它会变化（get-avatar 也会报告头像版本 ID）。把它保存下来，下次查询时比较即可。

get-presence 为什么这么慢？ 单次调用可能需要约 17 秒，所以请设置较长的超时，并且只对信号确实重要的联系人调用。

userHash 可以重复使用吗？ 可以，24 小时内有效。同一个号码的头像、签名、企业资料和在线状态调用都可以复用它，之后再重新做一次注册校验获取新的 hash。

立即体验

在 WhatsApp 号码校验页面在线获取资料，或阅读 get-avatar、get-about、get-biz-profile 与 get-presence 接口文档。查看定价了解每次请求的成本。