WhatsApp 号码查询 API:先付存在性检查,再决定要不要补资料
陈柯在广州做跨境卖家入驻。每天进审的店主手机号,默认都要能聊 WhatsApp:号在不在网上,工单要不要头像、签名,还是一张商家名片。上个季度他把 check-exist-by-phone 接上之后,对每一行都连打 get-avatar、get-about、get-biz-profile、get-presence。点数耗在从没注册过的号上,耗在他把 isExist=null 当成命中的行上,也耗在坐席其实只要一个字段、脚本却走了四跳的地方。
WhatsApp 号码查询 API 首先是预算问题,其次才是资料问题。存在性检查便宜;头像、签名、在线、商家都挂在 24 小时的 userHash 后面,而这张票只该在真正命中时签发。打开本页或复制示例不会发查询;真正执行命令才会,并且扣点数。
登录 后从控制台复制你有权使用的 Key,服务端用 OPENDATA_API_KEY 读取。curl 里的 YOUR_API_KEY 只是占位符。Key 走查询串,不要写进工单、截图、前端脚本或仓库。
未命中的号码不要补资料
名单先过注册检查。isExist 不是字面 true 之前,不要打任何资料接口。
默认的便宜分类器用 check-exist-by-phone:一次 GET、一个完整国际号码。带不带 +、有没有空格或连字符、用不用 00 前缀都可以,接口会拆国家区号。文档示例形态是 15551234567,只说明位数和区号,不保证是真实在网账号。
区号和本地号本来就分列存的,用 check-exist-by-cc-phone:cc 是不带 + 的拨号前缀(1 到 4 位),phone 是本地号码(6 到 15 位,不要前导零)。如果后面完全不补资料——注册页开关、能不能把会话切到 WhatsApp——用 check-active 拿一个活跃标志即可,不会签发 userHash。签发一张立刻丢掉的票,也是在花钱。
名单是文件而不是表单时,batch-check-10 一次最多查 10 个号,每个号返回 exist 和 isBusiness。这个商家标志不需要 userHash。只要把个人和店铺切开,停在这一步。完整的名单清洗见批量校验;单个号码的三态路径见如何检测号码是否在用 WhatsApp。
isExist 是三态,点数最先从这里漏:
true:已注册。只有这类行可以签发userHash。false:未注册。干净的未命中。落库,不要当超时重试,更不要去打头像、签名、在线或商家。null:暂时无法判断。退避后重试的是检查本身,不是资料跳。不要把null写成「没有 WhatsApp」,也不要把null当成可以补资料的通行证。
HTTP 状态和网关状态都不是 isExist。缺 Key、Key 无效、参数校验失败、传输失败,会表现为 HTTP 4xx/5xx,或网关 code 不是 200。这类信封里没有 WhatsApp 结论——该补凭证或改请求,不要写 false。HTTP 2xx 且网关 code 为 200,只说明检查送达了,这时才读 isExist。送达的 null 仍是业务结果:不确定,不是崩溃。返回会包成 {"code", "data"},平台可能再包一层,要拆到真正带 isExist 的对象。
陈柯第一批点数,就是栽在 Python 的真值判断上。None 和 False 都是假值,if not isExist 会把未命中和待重试写成同一支;反过来 if isExist: 会让 null 走进资料调用。分类必须用 is True / is False / is None。
命中才签发 userHash
isExist 为 true 时,检查会返回一张有效 24 小时 的 userHash,以及 hasExtra(这个号有哪些补全字段)。已注册账号一定列出头像和签名;deviceName、email、waOldDeviceName 只在已知时出现。hash 绑在服务端已经解析过的那个号码上。资料接口不收电话号码参数。缺失、未知或过期的 hash 直接被拒,不会去查资料。
你不必登录 WhatsApp 账号,也不要自己造票。只有检查命中才会签发。把 isExist、userHash、hasExtra 和检查时间一起存。命中的 hash 在该时间加 24 小时内复用。窗口还没关就重新检查来「刷新」手里已有的 hash,是在浪费便宜跳;hash 过期了还去打 get-avatar,则是一次注定失败的往返。干净的未命中也缓存同一窗口,避免为同一句 false 付第二次钱。
check-active 和 batch-check-10 不给你这张票。下一跳真的要照片、签名或完整商家名片,必须对那个号走 check-exist。下一跳只是「在网,而且是不是店」,留在 batch-check-10,不要签发。
下面的脚本就是预算闸门。自行安装 requests,服务端导出 OPENDATA_API_KEY。它会拆信封、分三态、把命中的 hash 缓存 24 小时,并且——只有你传入 enrich 时——才花 一跳 资料。默认只检查。号码是文档形态,不保证命中。
import os
from datetime import datetime, timedelta, timezone
import requests
BASE = "https://api.opendata-api.com/api/project/whatsapp"
KEY = os.environ["OPENDATA_API_KEY"].strip()
HASH_TTL = timedelta(hours=24)
CACHE = {} # number -> check record
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 failure: {response.status_code}")
body = response.json()
if not isinstance(body, dict) or body.get("code") not in (200, "200"):
raise RuntimeError("Gateway business failure; inspect redacted diagnostics")
# 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 check_exist(number):
cached = CACHE.get(number)
if cached:
checked_at = cached["checked_at"]
if datetime.now(timezone.utc) - checked_at < HASH_TTL:
return cached
found = call("check-exist-by-phone", phoneNumber=number)
exists = found.get("isExist")
record = {
"isExist": exists,
"userHash": found.get("userHash") if exists is True else None,
"hasExtra": found.get("hasExtra") if exists is True else None,
"checked_at": datetime.now(timezone.utc),
}
if exists is not None: # cache hits and clean misses; do not cache undetermined
CACHE[number] = record
return record
def lookup(number, enrich=None):
"""enrich is one of: avatar, about, biz, presence, or None (check only)."""
record = check_exist(number)
exists = record["isExist"]
if exists is None:
return {"number": number, "status": "undetermined"}
if exists is False:
return {"number": number, "status": "not_on_whatsapp"}
out = {
"number": number,
"status": "registered",
"hasExtra": record.get("hasExtra"),
}
user_hash = record.get("userHash")
if not user_hash or enrich is None:
return out
if enrich == "avatar":
avatar = call("get-avatar", userHash=user_hash)
out["pictureSet"] = avatar.get("pictureSet")
out["reason"] = avatar.get("reason")
elif enrich == "about":
about = call("get-about", userHash=user_hash)
out["about"] = about.get("about") or None
elif enrich == "biz":
biz = call("get-biz-profile", userHash=user_hash)
out["isBusiness"] = biz.get("isBusiness")
elif enrich == "presence":
presence = call("get-presence", timeout=60, userHash=user_hash)
out["visible"] = presence.get("visible")
else:
raise ValueError("enrich must be avatar, about, biz, presence, or None")
return out
if __name__ == "__main__":
print(lookup("15551234567", enrich=None))
先对整份文件跑 lookup(number, enrich=None),把状态落库。再只对「已注册、而且人会看到」的子集,带上一个 enrich 再跑。进程内 CACHE 只是示意;生产里同一条记录应该跟联系人放在一起,带着时间戳,免得第二个 worker 再签一张票。
头像、简介、在线、商家只挑一个
这四项各自扣一次。工单真正展示哪个,就只打哪个。字段为空是已经付过钱的答案,不是「以防万一」再打下一跳的理由。
get-avatar:pictureSet=true时给你临时照片链接,以及头像变更会跟着变的版本 ID。工单要留脸,当场下字节,不要长期热链。pictureSet=false表示没头像或隐藏了,reason说明原因。到这里就结束。get-about:签名文本和头像版本 ID。about为空表示没设或隐藏。不要重试到「必须出现一句口号」。get-biz-profile:商家名、认证等级、简介、地址、邮箱、网站、入驻时间。个人号返回isBusiness=false。如果只要这个布尔值,batch-check-10已经给过,不必 hash。get-presence:在线或最后在线,且受隐私限制。对方不是你的联系人、最后在线也不是「所有人」时,visible=false,绕不过去。单次最长约 17 秒,超时要给足,只在这个信号值得等待和点数时才打。
稀疏附加项(get-device-name、get-email、get-wa-old-device-name)只在 hasExtra 列出时才存在。邮箱是打码的备份地址,不是店铺客服箱。没列出的不要打。
各字段长什么样、空值意味着什么,见WhatsApp 头像、签名与在线状态。做「默认有一张脸」的界面之前先读它。
陈柯后来在工单上只留一列:头像、签名或商家名片,按队列选。客服看脸,销售看 isBusiness 和认证名。半夜进审的单,没有人会为最后在线干等 17 秒。在线状态不进默认路径。
这个项目不是什么
这是公开号码情报,不是 WhatsApp 客户端。它不发消息、不读会话、不开会话——那是另一个项目。跑这些查询不需要你自己的 WhatsApp 账号,需要的是有权使用的平台 Key,以及你有合法依据处理的号码。
它不保证已注册号码一定有头像、签名、最后在线、设备名或商家名片。隐私设置会藏这些字段。空是合法结果。对着干净的未命中、pictureSet=false、空的 about 或 visible=false 重试到「必须出现一份资料」,只会烧点数。
它也不是给 CRM 每一行都补全的理由。多数名单里,未命中是大头,「其实只要 registered=yes」也是大头。先为 check-exist-by-phone 付钱(或用 batch-check-10 一次十个)。命中才签发 userHash。第二跳最多花一次,而且只花在人会看见的行上。不要把 HTTP 200 当成「在 WhatsApp 上」。不要把 isExist=null 当成 false。不要把不确定的检查缓存成未命中。
它不是 KYC,不是法定姓名,也不是证件号。一张公开头像和一句签名证明不了身份。单次费用见定价。只处理你有权使用的号码,Key 放服务端,并遵守 WhatsApp 的条款。