WhatsApp 资料 API:userHash 之后的头像 URL、简介和 last-seen
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 条款。