WhatsApp Checker API：从后端检测注册状态

本文介绍了后端团队如何调用 WhatsApp Checker API，在 WhatsApp 注册检测、WhatsApp 头像检测和 WhatsApp 商业账号检测之间进行选择，以及如何处理无法判定的结果。

WhatsApp Checker API 可接收来自您服务器的电话号码，并在同一响应中返回该号码在检测时是否已注册 WhatsApp 账号。在 WA Lookup 中，单个号码请求通过 POST /api/v1/check 发送，需在 X-API-Key 请求头中包含密钥，并通过 service_type 选择注册检测、头像检测或商业账号检测；而 POST /api/v1/batch-check 支持在一次同步请求中处理最多 100 个号码。如果检测结果无法判定，API 将返回一个非零的业务代码，后端代码应将其视为“稍后重试”，而非“未注册”结果。

WhatsApp Checker API 为后端提供的功能

针对此查询的搜索结果大多是市场列表和 API 封装工具，它们仅显示电话参数以及“是”或“否”的答案。其中一些工具通过连接的 WhatsApp 会话运行检测，因此当该电话离线时，API 就会停止响应。很少有文档解释这些答案对消费代码的意义，或如何处理无法获得答案的情况。

对于后端工作，一个实用的思维模型很简单：WhatsApp Checker API 对每个号码回答一个问题：在检测运行时，该号码是否注册了 WhatsApp 账号？这是一个针对单一平台的账号存在信号。它是以下场景的良好输入：

• 在尝试其他渠道前，判断是否值得通过 WhatsApp 联系对方；
• 清理 CRM 或潜在客户数据库中的电话字段；
• 为注册或入职审核队列添加背景信息。

这并非关于谁持有该号码或对方是否同意被联系的声明。请将您的同意记录和联系历史作为独立输入，并存储每次检测的日期，以便日后刷新数值。

如何为单个号码调用 WhatsApp Checker API

单号调用是一次 HTTPS 请求对应一次响应。无需创建任务，无需轮询，也无需暴露回调 URL。

1. 标准化为 E.164 格式。 按照 ITU-T Recommendation E.164 标准，发送带有加号、国家代码和用户号码的完整格式。去除空格、括号和国家长途前缀。例如，本地书写为 0151 2345 6789 的德国移动号码应变为 +4915123456789。Google 的 libphonenumber 库可使用默认区域解析原始输入，比手写的字符串规则更安全。
2. 选择检测类型。 根据结果驱动的决策，将 service_type 设置为 ws、ws_avatar 或 ws_business。
3. 从服务器进行身份验证。 将密钥放入 X-API-Key 请求头中发送。请从密钥存储或环境变量配置中加载，切勿将其放置在浏览器代码、移动应用包或公共仓库中。
4. 发送 POST /api/v1/check。 该号码的检测结果将直接在同一请求的响应中返回。
5. 根据结果进行分支处理。 已完成的结果包含所选检测的答案。非零的业务代码表示当前无法判定该检测结果。

请根据当前的 WA Lookup API 文档构建请求体和响应解析逻辑。其他提供商示例中的负载格式各异，盲目复制是导致集成错误的常见原因。

选择检测类型：ws、ws_avatar 或 ws_business

service_type 的值决定了返回的信号类型。请选择能回答您代码所需问题的最窄范围检测，因为无论结果是“已注册”还是“未注册”，每次完成的检测都会计费。

ws

注册检测。它告知后端提交的号码在检测时是否拥有已注册的 WhatsApp 账号。这是渠道决策、列表清理和注册审核的默认选择。

ws_avatar

头像检测。除注册状态外，它还会报告是否提供个人资料照片，并在有照片时提供链接。该链接可能为空字符串。适用于联系人记录丰富化，或为人工审核员提供更多背景信息。缺少照片并不代表该号码未注册。

ws_business

商业账号检测。除注册状态外，它还会报告该账号是否为 WhatsApp 商业账号（即通过 WhatsApp Business app 或商业平台创建的账号类型）。销售团队使用此功能将商业账号与标准账号区分开来。它仅描述账号类型，并非对合法公司身份的核实。

使用批量检测端点检查最多 100 个号码

当后端已拥有一个号码组（例如夜间导入或包含多个联系人的表单提交）时，POST /api/v1/batch-check 可在一次同步请求中发送最多 100 个号码。整个批次的结果将在该请求的响应中返回，否则整个请求将失败。

这种行为决定了客户端代码的编写方式：

• 分块处理大型列表。 将输入拆分为 100 个或更少的组，并依次发送，或控制并发请求数量。
• 将失败的请求视为一个整体。 如果批处理请求本身失败，请重试该批次；不要为其中的号码标记任何结果。
• 仍需读取每个号码的结果。 在成功的批次中，每个号码都有其独立的已完成或无法判定的结果，因此单号流程中的分支逻辑适用于每一条目。
• 先进行去重。 在分块前进行标准化通常能发现以不同本地格式书写的重复号码；对每个号码仅检测一次可保持支出可控。

批量端点仍然是“即时响应”流程。它是应用程序代码处理几十或几百个号码的正确工具，不适用于包含超大列表的文件。

处理无法判定的检测和请求错误

最昂贵的集成错误是在检测未得出结论时，将“未注册”写入数据库。已完成的“未注册”结果是一个确切的答案，而一个非零的业务代码根本不是答案。

实用的分支模式：

请对重试使用指数退避策略并限制尝试次数，以免临时问题演变为重复调用的爆发。将无法判定的号码保持在“待重试”等独立状态，以便报告能将其与已确定的结果区分开来。

在生产环境中运行集成

一些操作习惯能使 Checker 集成更易于维护：

• 遵守文档中的控制要求。 当前的 API 文档描述了每用户的并发和超时控制。请根据这些控制要求调整并发请求数量，并在扩展规模时查阅文档，而不是假设存在固定的每分钟限额。
• 关注账号余额。 一个账号余额涵盖仪表板、REST API 和 MCP 服务器，因此大规模 API 作业和手动仪表板检测会消耗同一池中的余额。在大规模运行前，请在仪表板中检查余额。
• 记录日志但不泄露信息。 记录请求结果和错误代码，但在通用应用程序日志中掩码电话号码，且绝不要记录 API 密钥。
• 轮换密钥。 仪表板负责管理 API 密钥；如果密钥可能已泄露，请轮换密钥并同步更新密钥存储。
• 记录背景信息。 存储检测类型和时间。数月前的结果描述的是该号码当时的状态，而非今日。

WhatsApp 的 Terms of Service 限制对其服务进行自动化或未经授权的访问，这也是团队放弃驱动个人会话的脚本，转而使用带有独立密钥的托管式 API 的原因之一。

何时使用文件任务而非 API

对于超大列表，异步批量任务是更好的选择：上传一个每行包含一个号码的 TXT 或 CSV 文件，等待处理，然后下载 result.csv。批量任务使用 POST /api/v1/bulk-tasks 提交，并使用 GET /api/v1/bulk-tasks/{id} 跟踪进度，且适用 API 文档中描述的每产品限额。文件应包含基本属于同一个国家的号码，且批量服务不支持中国大陆、香港或澳门的号码。批量余额在提交时预留，处理后退还未使用部分。

对于大多数响应用户操作或小规模导入的后端功能，同步的单号和批量检测调用仍然是更简单的选择。

常见问题解答

团队在投入生产前如何测试 WhatsApp Checker API？

从团队已知预期结果的少量号码（如公司电话）开始，并从预发布环境调用单号端点。符合条件的新账号在注册后会自动获得 100 次免费检测额度，这通常足以验证客户端代码中的“已注册”、“未注册”和“重试”路径。

当号码返回“无法判定”时，后端应如何处理？

将结果字段留空，记录业务代码和时间，并将该号码放入带有退避策略的重试队列中。为无法判定的检测写入“未注册”值会破坏列表数据，并导致后续错误的渠道决策。

批量检测端点与文件上传的工作方式有何不同？

是的。批量检测端点在同一请求的响应中返回最多 100 个结果。文件上传则创建一个在后台处理的异步批量任务，处理完成后可下载 result.csv。

CRM 集成默认应使用哪种检测类型？

注册检测 ws 涵盖了大多数渠道和数据质量决策。仅在 CRM 中的字段确实需要头像可用性或账号类型时，才添加 ws_avatar 或 ws_business，因为每次完成的检测都会计费。

了解更多

选择符合您工作流下一步的产品信息。

• 查看产品文档 →
• 联系团队 →