如何查询手机号是否注册了 WhatsApp（API 教程）
如果你的业务会从注册表单、CRM 导入、广告线索或外购名单中收集手机号，其中相当一部分号码其实根本无法在 WhatsApp 上触达。给这些从未注册的号码发起营销或引导流程，既浪费预算，又拉低送达率。WhatsApp 号码检测能在你发出任何消息之前，先告诉你一个号码是否真的注册了。
本文介绍如何检测单个号码、怎样读懂三种可能的结果，以及如何分批检测号码，并附上可以直接复制的 Python 代码。
「检测号码」会返回什么
一次注册检测会接收一个手机号，告诉你它是否绑定了可用的 WhatsApp 账号。对已注册的号码，完整的检测还会返回 userHash 和 hasExtra 摘要，让你可以在第二个独立的步骤里去拉取公开资料（头像、签名、企业资料）。如果你只需要「是或否」的答案，就完全不必走第二步。
第一步：获取 API Key
所有请求都通过 API Key 鉴权：
每个新账户都赠送免费点数，可以不花一分钱先测试。
第二步：检测单个号码
调用 check-exist-by-phone，传入完整的国际号码。号码带不带开头的 + 都可以，空格、连字符或 00 前缀也能接受，国家区号和本地号码会被自动解析：
curl "https://api.opendata-api.com/api/project/whatsapp/check-exist-by-phone?key=YOUR_API_KEY&phoneNumber=15551234567"答案在 isExist 字段里，它有三种状态：
true：号码已注册 WhatsApp。响应里同时带有userHash（有效期 24 小时）和hasExtra。false：号码没有注册。null：结果不确定。请稍后退避重试，不要把这个号码标为不可达。
如果你的数据里国家区号和本地号码是分开存储的，check-exist-by-cc-phone 把它们作为 cc 和 phone 两个参数。如果只是想在注册流程里快速得到是否活跃的答案，check-active 对完整号码直接返回一个活跃标志，不涉及 userHash。
整理输入依然是好习惯：只保留数字和国家区号，在花费一次请求之前先剔除明显错误的值，并为每个联系人保存唯一的标准格式，这样重复数据就会合并。
第三步：批量检测号码
逐个请求检测成千上万条线索太慢了。batch-check-10 每次请求最多检测 10 个号码。把号码用逗号分隔后放进 accounts，响应会为每个号码分别报告它是否在 WhatsApp 上、是否为企业账号：
curl "https://api.opendata-api.com/api/project/whatsapp/batch-check-10?key=YOUR_API_KEY&accounts=15551234567,15557654321,442071234567"名单更长时，按每 10 个一组循环处理。完整的策略，包括重试和结果保存，请看如何批量校验 WhatsApp 号码。
可复用的 Python 函数
import requests
API_KEY = "YOUR_API_KEY"
BASE = "https://api.opendata-api.com/api/project/whatsapp"
def is_on_whatsapp(number, retries=2):
"""Return True, False, or None when the answer stays indeterminate."""
for attempt in range(retries + 1):
resp = requests.get(
f"{BASE}/check-exist-by-phone",
params={"key": API_KEY, "phoneNumber": number},
timeout=30,
)
resp.raise_for_status()
data = resp.json()
# A reply can be wrapped more than once as {"code": ..., "data": {...}}
while isinstance(data, dict) and "code" in data and isinstance(data.get("data"), (dict, list)):
data = data["data"]
if isinstance(data, dict) and data.get("isExist") is not None:
return bool(data["isExist"])
return None
for n in ["15551234567", "442071234567"]:
print(n, is_on_whatsapp(n))在注册表单里调用检测的方式也是一样的。把 None 当作「现在无法确认」，让用户继续操作，然后在后台再次检测。
正确解读结果
肯定的结果表示该号码有一个可用的 WhatsApp 账号。它并不代表对方愿意收到你的消息，消息会被阅读，也不能证明号码属于你以为的那位联系人。请记住这些局限：
- 已注册不等于已同意。 授权是另一项独立的要求，WhatsApp 针对未经请求消息的规则依然适用。
- 否定的结果有用，但不是定论。 人们可能晚些时候才安装 WhatsApp，所以请按计划周期复查。
- 企业标识只是提示。 它帮你决定如何称呼联系人，而不是决定要不要信任它。
当某个渠道的答案是否定时，下一步往往应该是换一个渠道。线索核验工作流介绍了如何把 WhatsApp 与 Telegram、Viber、Signal 的检测结合起来；对于通过检测的号码，WhatsApp 号码查询指南介绍了怎样做资料补全。
常见应用场景
- 线索名单清洗：在发起营销前剔除没有 WhatsApp 的号码，只为可触达的联系人付费。
- 注册验证：在把验证码或客服路由到某个号码之前，先确认它支持 WhatsApp。
- CRM 数据补全：为已注册联系人补充头像、签名和企业资料。
- 反欺诈筛查：在引导流程中标记一次性或从未注册的可疑号码。
最佳实践
- 先做归一化。 保留数字和国家区号，并保存唯一的标准格式。
- 先去重再检测，避免同一个号码重复消耗点数。
- 缓存结果。 保存结果时带上时间戳，按计划周期（比如每隔几周）复查，不必每次发送前都查。
- 重试
null结果。 它们是暂时性的，不是否定的结论。 - 遵守平台规则。 只检测你有正当依据处理的号码，并遵守 WhatsApp 的条款和适用于你的隐私法规。
常见问题
不给对方发消息，怎么检查一个号码有没有 WhatsApp？
用完整的国际号码调用 check-exist-by-phone，isExist 字段会告诉你号码是否已注册，而且没有人会收到消息。如果只需要「是或否」，check-active 会直接返回一个活跃标志。
检测接口支持什么格式的手机号？
包含国家区号的完整国际号码。带不带开头的加号都可以，空格、连字符或 00 前缀也会被自动解析。如果你的数据把国家区号单独存储，请使用 check-exist-by-cc-phone。
结果是 null 怎么办？
这表示当时结果不确定。请稍后退避重试，不要把 null 当作「没有 WhatsApp」。
一次最多能检测多少个号码？
batch-check-10 每次请求最多 10 个。名单更长时，拆成每组 10 个循环处理。
肯定的结果是不是代表我可以给这个号码发消息？ 它只代表该号码有一个可用的账号。你仍然需要对方的同意，而且 WhatsApp 针对自动化和批量消息的规则依然适用。
立即体验
你可以在 WhatsApp 号码校验页面交互式地测试，也可以阅读 check-exist-by-phone、check-active 与 batch-check-10 的接口文档。准备集成时，获取一个 API Key，从账户赠送的免费点数开始即可。