WhatsApp 资料 API:userHash 之后的头像 URL、简介和 last-seen

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

url 才是人口中的 WhatsApp 头像。注册校验的 200 里没有它。check-exist-by-phone 最多给你一张 24 小时的 userHash;照片 URL、简介、last-seen 都在后面的对象里,而且只能把这张 hash——不是手机号——交给 get-avatar、get-about 和 get-presence。

本文顺着这些字段走,不是又一篇「号码在不在 WhatsApp」教程。三态 isExist 看如何判断号码是否在 WhatsApp;先不先花钱做校验看号码查询的预算。打开页面或复制示例不会发查询。真正跑命令才会扣点。登录后从控制台复制授权密钥,服务端用 OPENDATA_API_KEY 读。curl 示例里的占位符是 YOUR_API_KEY。密钥走查询字符串,别贴进工单、截图和仓库。

真正会入库的三个公开字段

能进 CRM 的公开资料是三条记录,不是一个大对象。

  • 头像。 get-avatar:pictureSet、临时 url、头像一换就变的 pictureId,以及没有照片时的 reason。
  • 简介。 get-about:about(未设或隐藏时为空或 null),外加同一个 pictureId。
  • last-seen / 在线。 get-presence:先看 visible,为真才有 online、lastSeenMs、lastSeenIso。

get-biz-profile 是商家的第四个对象:isBusiness=true 时才有名称、认证等级、简介、地址、邮箱、网站、入驻时间;个人号是 isBusiness=false。设备名、掩码备份邮箱、旧设备名只在校验的 hasExtra 里出现过才去拉。下面只走三条会入库的公开字段。

你手里已经有一张来自 isExist=true 的 userHash。资料接口不收手机号。号码在出票时已经解析完。缺 hash、不认识或过期,直接拒,不会去查资料。同一张票在 24 小时内可复用于头像、简介、企业资料和在线状态。文档里的 15551234567 只是号码形态,不是保证存在的账号,更不是这些接口的入参。

userHash 本身不是资料字段,别展示给销售、别写进对外报表。它只是 24 小时的授权票。过期了就重新走校验拿新票,不要把旧票和手机号拼在一起「补救」。把三条记录并成一行联系人时,缺字段就留空,不要用校验里的 hasExtra 去填假头像——那张地图只说明「可以去问」,不保证问了有值。

HTTP 状态和网关状态压在字段之上。缺密钥、未授权、参数错、传输失败,是 HTTP 4xx/5xx 或网关 code 不是 200——信封里没有 WhatsApp 资料。响应常包成 {"code","data"}(有时两层),要剥到看见 pictureSet、about 或 visible。HTTP 200 且网关 code 为 200 只说明这次调用送达了。随后的 pictureSet=false、空 about、visible=false 是业务答案,不是崩溃。

hash 进去,照片 URL 出来

get-avatar 只收 userHash。

# Documented request shape — running it spends credits. USER_HASH is not a live ticket.
curl "https://api.opendata-api.com/api/project/whatsapp/get-avatar?key=YOUR_API_KEY&userHash=USER_HASH"

先读 pictureSet。为 true 时,url 是临时公开照片链接。立刻把字节拉下来,存字节(或你自己的持久副本)。不要把 url 当头像存:链接会过期。pictureId 是版本号,和联系人一起留下。下次补全时值变了就重新下载,没变就跳过。get-about 也会给 pictureId,同一套 id。

pictureSet 为 false 时,reason 说明没设或被隐私藏起来。这是有效答案。别当成坏 hash 去重试,也别写成「不在 WhatsApp」——注册与否早就定过了。hash 出错是网关拒绝,不会伪装成 pictureSet=false。也不要自己拼照片地址:接口没给 url 就没有可下的图。把 pictureId 塞进某条 CDN 路径是猜的,猜错了会把失败当成隐私隐藏。

import os

import requests

BASE = "https://api.opendata-api.com/api/project/whatsapp"
KEY = os.environ["OPENDATA_API_KEY"].strip()


def call(operation, timeout=30, **params):
    response = requests.get(
        f"{BASE}/{operation}",
        params={"key": KEY, **params},
        timeout=timeout,
    )
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"http {response.status_code}")
    body = response.json()
    # Envelope may wrap more than once as {"code": ..., "data": {...}}
    while isinstance(body, dict) and "code" in body and isinstance(body.get("data"), (dict, list)):
        if body.get("code") != 200:
            raise RuntimeError(f"gateway {body.get('code')}: {body.get('message')}")
        body = body["data"]
    return body


def avatar_record(user_hash):
    payload = call("get-avatar", userHash=user_hash)
    record = {
        "picture_set": payload.get("pictureSet"),
        "picture_id": payload.get("pictureId"),
        "reason": payload.get("reason"),
        "photo_bytes": None,
    }
    if payload.get("pictureSet") is True and payload.get("url"):
        image = requests.get(payload["url"], timeout=30)
        image.raise_for_status()
        record["photo_bytes"] = image.content
    return record

这段代码不会凭空造出命中。USER_HASH / user_hash 必须是你已经拿到的票。复制代码块不会去拉照片。

简介和 last-seen 都是可选

把简介或最后在线当成必填的团队,会丢掉大部分已注册号码。这两项只有对方公开时才公开。缺了不等于接口坏了,更不等于号码注销。

get-about 返回 exists、about、pictureId。about 空或 null:没写签名,或藏了——存空,别重试。exists=false 表示未注册;没有真校验发出的 hash,就不该走到这里。如果跳过了 get-avatar、只想做廉价的换头检测,也可以用这里的 pictureId。about 和个人号上的自我介绍是同一条签名,不是商家简介;商家那套文案在 get-biz-profile 的 description 里,两套不要互相覆盖。

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

get-presence 又慢又受隐私卡住。你不是对方联系人、且最后在线/在线没设成所有人,就拿不到:visible=false。绕不过去。单次最多大约 17 秒,客户端超时至少给到 60 秒;默认补全应当跳过它。

get-biz-profile 同样可选:个人号 isBusiness=false,没有商家字段。不要把掩码备份邮箱当成企业联系邮箱;那是另一个对象,而且只有 hasExtra 写过才去要。

def about_record(user_hash):
    payload = call("get-about", userHash=user_hash)
    about = payload.get("about")
    return {
        "exists": payload.get("exists"),
        "about": about if about else None,
        "picture_id": payload.get("pictureId"),
    }

头像、简介、以及(仅在需要时)在线状态,写进你已经校验过的那条号码记录。不要再传手机号。

在线状态是快照,不是长连接

get-presence 就是一次 GET。不是 websocket,不是订阅,也不是「上线了通知我」。载荷只是采集那一刻能看见的东西。

visible 为 true 时再读 online、lastSeenMs(毫秒时间戳)、lastSeenIso(ISO-8601)。这些键只在可见结果里出现。visible 为 false 就停。没有 last-seen 可解析,循环调用也抬不起隐私开关。lastSeenMs 和 lastSeenIso 是同一时刻的两种写法,入库留一个即可;比较时别一个当本地时区、一个当 UTC 再减一遍。快照里没有「正在输入」或「刚刚在线」这种客户端装饰字段。

def presence_snapshot(user_hash):
    payload = call("get-presence", timeout=60, userHash=user_hash)
    if payload.get("visible") is not True:
        return {"visible": False}
    return {
        "visible": True,
        "online": payload.get("online"),
        "last_seen_ms": payload.get("lastSeenMs"),
        "last_seen_iso": payload.get("lastSeenIso"),
    }

墙钟时间长是正常的。没有响应体的超时是传输问题,不是 visible=false。分开处理:超时再退避重试;已送达的隐藏结果直接入库。当成实时在线通道几秒轮一次,既烧点,也绕不过隐私。采集时刻过了,人后来上线了你也看不见,除非再花一次 get-presence;再花一次仍然可能 visible=false。把一次隐藏结果缓存到和 userHash 同样的 24 小时窗口,避免同一张票被当成实时通道刷爆。

接口页:get-avatar、get-about、get-presence、get-biz-profile。产品页:WhatsApp 号码校验。费用见定价。把头像和别的信号放进同一套评分,见线索核验工作流。

容易把 CRM 写空的做法:给头像/简介/在线状态传 phoneNumber;把临时 url 当照片存;把 pictureSet=false、空 about、visible=false 当成 HTTP 失败;把 last-seen 设成必填;给在线状态只留 5 秒超时;看见 HTTP 200 就当有头像;把带密钥的 URL 贴进工单;hash 过期或根本没出过票还去拉资料;把在线状态当成长连接去轮询。资料按个人信息处理,只处理你有合法依据的号码,并遵守 WhatsApp 条款。