如何查询手机号是否注册了 WhatsApp(API 教程)
业务说的「这个号在不在 WhatsApp 上」,落在 JSON 里其实是一个字段:check-exist-by-phone 拆包之后的 isExist。HTTP 200 不是它,网关 code: 200 也不是它。userHash 只在 isExist 为 true 时才签发,有效期 24 小时,用来做后面的资料查询,不能反过来当「在不在」的证据。把状态行当成注册结论,或把一次十个的批量结果当成单个布尔,CRM 就会把 null、空行、根本没给出业务结论的请求,统统写成「未注册」。
这篇讲的就是这些失败形态:空结果、未判定、HTTP 与业务层不是一回事,以及单个号码和一批十个不要共用同一套读写。检测不会给对方发消息。打开本页或复制示例不会发出查询;真正跑命令才会,并且会扣点数。授权密钥放服务端:登录 后从控制台复制,用环境变量 OPENDATA_API_KEY 读取。查询 URL 带着密钥,不要整段贴进工单、截图或仓库。
先说清楚「在 WhatsApp 上」指哪个字段
三个接口都能回答「在不在」,但键名不是同一个。把它们写成同一个布尔列,报表里的「未注册率」会把未判定、空批次、密钥错误混在一起,后面补资料和渠道路由都会跟着错。Signal 那篇讲的是 registered 三态;这里要先钉死读哪一个键,再谈单个还是十个一批。
单个完整国际号码走 check-exist-by-phone,参数是 phoneNumber。加号可有可无,空格、连字符、00 前缀都能解析。网关信封拆掉以后,只认 isExist:
true:已注册。同对象里可能有userHash和hasExtra,那是下一步补资料用的,不是「是」本身。false:未注册。干净的未命中,不要当超时再打。null:当时判不了。进队列,不要落成不可达。
区号和本地号码分列存的,用 check-exist-by-cc-phone 的 cc 与 phone,结论照样在 isExist。check-active 只给完整号码一个活跃标志,不签发 userHash。注册表单只要快答、后面不补头像时用它。不要到这份响应里找 isExist,那是另一个接口。
batch-check-10 更不是把 isExist 喊大声。accounts 里逗号分隔最多十个完整号码,每行给 exist(在不在)和 isBusiness(是不是企业号)。isBusiness 只适合分段,不能覆盖注册结论:个人号 isBusiness 为 false,仍然在 WhatsApp 上。
HTTP 和网关 code 在这些字段之上。缺密钥、密钥无效、参数校验失败、传输失败,表现为 HTTP 4xx/5xx,或网关 code 不是 200。这类信封里没有 WhatsApp 结论——该补凭证或改请求,不要写 false。HTTP 2xx 且网关 code: 200 只说明检查送达了,这时才读 isExist、活跃标志或每行的 exist。送达的 null 仍是业务结果:不确定,不是崩溃。拆包后没有对应键,或批量正文是空的,属于空/畸形,不是一份全否名单。空和未判定也不要合成一个「查失败」开关:空是这次没有可读的字段,未判定是字段在、值是 null。
下面的号码只是文档形态,不保证能查到注册。已注册也不等于对方同意收消息;授权是另一回事。明显缺位、缺区号的值先丢掉,再花钱去查。
一个号码,再十个
表单当场只有一个号。调用 check-exist-by-phone 或 check-active,等这一条的结论。为了「顺便用批量接口」去凑九个占位号,缺行会变成假的未注册,用户还得干等到一批根本不需要的结果。
洗名单才是另一件事。batch-check-10 用来减少往返:十个一组,把本次请求的号码和原始返回放一起,才能对上哪些输入根本没出现。批量 HTTP 200 不等于十个 exist=true。每一行只看自己的 exist,不要按数组下标去对 isExist——批量接口根本不叫这个名字。某行没有 exist、返回条数不够、整组传输失败,这十个(或缺的那几个)都是未判定——重试这一组,不要写成未注册。缺行比 false 更危险:它看起来像「查过了」,库里却是你补出来的否。isBusiness 可以旁记,不许覆盖 exist。
更长的名单按十个循环。先按规范格式去重,同一个号不要进两组各扣一次。文件级重试和续跑见如何批量校验 WhatsApp 号码。那边讲吞吐,未知仍然要留着,不能为了结单改成否。
已经拿到 isExist=true 的 userHash、下一步却想拉头像或签名,就停在检测这里。那是补全,不是本页的「在不在」。
不要把未知写成否
开头那种事故,多半是 Python 把三态当成布尔。None 和 False 都是假值:
# Wrong: null, missing, and false all look like "no"
if not payload.get("isExist"):
mark_unregistered(number)
分类必须用 is True / is False / is None。先拆 {code, data};网关 code 不是 200 就停在信封层。单次检测只重试未判定。次数用尽仍是 null,就保持未判定。
import os
import time
import requests
BASE = "https://api.opendata-api.com/api/project/whatsapp"
KEY = os.environ["OPENDATA_API_KEY"].strip()
def call(operation, **params):
try:
response = requests.get(
f"{BASE}/{operation}",
params={"key": KEY, **params},
timeout=30,
)
except requests.RequestException:
raise RuntimeError("Transport failure; inspect redacted logs") from None
if not 200 <= response.status_code < 300:
raise RuntimeError(f"HTTP failure: {response.status_code}")
try:
body = response.json()
except ValueError:
raise RuntimeError("Expected JSON") from None
while isinstance(body, dict) and "code" in body and isinstance(
body.get("data"), (dict, list)
):
if body.get("code") != 200:
raise RuntimeError("Gateway business failure; inspect redacted diagnostics")
body = body["data"]
return body
def classify_flag(value):
if value is True:
return "on_whatsapp"
if value is False:
return "not_on_whatsapp"
if value is None:
return "undetermined"
return "malformed"
def check_one(number, retries=2):
last_message = None
for attempt in range(retries + 1):
payload = call("check-exist-by-phone", phoneNumber=number)
if not isinstance(payload, dict):
return {"number": number, "status": "malformed"}
status = classify_flag(payload.get("isExist"))
if status == "on_whatsapp":
return {
"number": number,
"status": status,
"userHash": payload.get("userHash"),
}
if status != "undetermined":
return {"number": number, "status": status}
last_message = payload.get("message")
time.sleep(2 * (attempt + 1))
return {"number": number, "status": "undetermined", "reason": last_message}
def check_ten(numbers):
if not 1 <= len(numbers) <= 10:
raise ValueError("batch-check-10 accepts 1 to 10 numbers")
payload = call("batch-check-10", accounts=",".join(numbers))
# Keep requested inputs beside the raw payload; do not invent a miss
# for a number the batch did not return.
return {"requested": list(numbers), "result": payload}
# Documented example numbers — not guaranteed registrations.
print(check_one("15551234567"))
print(check_ten(["15551234567", "15557654321", "442071234567"]))
表单里把 undetermined 当成「这会儿确认不了」:让人先走完,后台再查,不要拿 null 卡住提交。true / false 带时间戳缓存,按周期复查——人会后装 WhatsApp;null 不能当「否」来缓存。报表里单独留一列「未判定」,别并进未注册率,否则运营会按错误的触达率排期。HTTP 401/403 是密钥问题,不是超时,再睡两秒也不会变成 isExist: true。同一号码不要并行打两次:并发重试会把点数打穿,结论还是那一个三态。
这篇看完该去哪
只在「在不在 WhatsApp 上」、以及 isExist、活跃标志、批量 exist 各自怎么失败时留在本页。上千条名单清洗看批量校验 WhatsApp 号码。isExist 为 true 之后要头像、签名、在线或企业资料,转向WhatsApp 号码查询和头像、签名与最后在线。检测不是发送,发送见通过 API 发 WhatsApp 消息。剩下的号还要换渠道,走线索核验工作流。
可在 WhatsApp 号码校验页面试用,或直接看 check-exist-by-phone、check-active、batch-check-10。超出新账户赠送点数时,对照定价。