如何查询手机号是否注册了 WhatsApp(API 教程)

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

业务说的「这个号在不在 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。超出新账户赠送点数时,对照定价。