WA Lookup 如何验证 WhatsApp 号码

完成一次检测

这一节讲同步实时检测：SaaS 网页后台与 REST API 的同步接口使用同一套检测服务和响应含义。名单非常大时另有异步批量任务，见文末。

1. 1

   提交号码

   提交需要检测的号码，并按 API 文档要求使用号码格式。

2. 2

   选择产品

   ws 查询注册状态，ws_avatar 增加头像字段，ws_business 增加商业账号字段。需要活跃天数时，可用异步批量检测的对应产品。

3. 3

   读取结果

   在同一个响应中读取 registered；需要更新状态时重新检测。

提交号码要用什么格式

WA Lookup 每次检测接受一个号码，格式为 E.164：加号、国家区号、然后是不带空格和符号的号码，例如 +17253100591。这也是 WhatsApp 内部保存号码的格式，因此这样写的号码只对应一个账号。没有国家区号的号码无法可靠检测——同一串数字在很多国家都存在。

• 务必带国家区号，不要依赖您自己账号所在的国家。
• 去掉空格、横线、括号以及国内拨号用的前导 0，只保留 + 和数字。
• 格式不对的号码会在扣费前被拒绝；格式被拒不是"未注册"。

registered 代表什么？

registered 就是一次 WhatsApp 检测的答案。它只出现在成功响应里，是一个布尔值：true 表示请求那一刻该号码已注册 WhatsApp，false 表示未注册。其它情况——超时、无法判定、号码无效——都以错误码返回，并且 WA Lookup 会自动退回这次检测的费用。所以没有 registered 字段绝不等于"未注册"，它只说明这次检测没有产出结果。这个值反映的是您发起请求的那一刻：账号随时会新建或注销，要用旧结果做决策前请重新检测，不要把结果缓存几周。

• registered=true 表示已注册。
• registered=false 表示未注册。
• 其他情况请根据 API 返回的 code 处理，不要自行推断 registered。

按需选择产品

选择能够回答当前问题的最小实时产品即可；完整字段定义请查看 API 文档。

• ws 返回注册状态。
• ws_avatar 另外返回头像相关字段；没有可用头像地址时，avatar_url 为空字符串。
• ws_business 另外返回商业账号字段。

结果的使用边界

检测结果反映请求时的状态，不是身份认证或联系许可。

• 不能据此确认号码所有者，也不能确认此刻是否在线或消息内容；批量活跃度产品返回的是距最近一次活跃的天数，不是实时在线状态。
• 已注册不代表已取得联系该号码的同意。
• 业务需要最新状态时，应重新发起检测。

名单非常大时：异步批量选项

网页多号检测与 API 多号接口覆盖绝大多数名单。只有名单远超这些上限时，才值得把整份文件作为一个异步批量任务提交——提交时选定名单所属国家，名单应基本属于这一个国家。

• 在批量检测页或通过 API 上传 .txt / .csv，一行一个 E.164 号码。
• 提交任务时选定号码所属的国家/地区，名单应基本属于这一个国家；混入太多别国号码，任务会在后台预处理时失败，不会送去检测，并全额退款。
• 提交时按有效行数冻结相应余额，只对实际返回结果的号码计费，差额自动退回。
• 任务在后台执行，完成后下载结果文件；失败则全额退款。