如何准备 CSV 或 TXT 名单做 WhatsApp 实时号码检测

一份实用工作流程指南：为 WhatsApp 实时检测准备 CSV 或 TXT 号码名单，包括 E.164 格式化、选择服务类型，以及通过同步单号与多号接口获取账户存在信号。

WA Lookup 以实时检测 WhatsApp 账户存在信号为主：单个号码提交到同步单号接口，最多 100 个号码提交到同步多号接口 POST /api/v1/batch-check，完成结果都在发起请求的同一次 HTTP 响应中返回，无需等待任务。要把 CSV 或 TXT 名单交给它处理，须严格按照 E.164 国际编号标准格式化所有标识符，清除非数字字符和本地前缀，并根据工作流程需求选择服务类型：ws（基础注册状态）、ws_avatar（包含头像可用性）或 ws_business（识别 WhatsApp Business 账户）。远超一次实时请求的整份文件，也可以作为异步批量任务上传（上传、等待、下载）。

理解 WhatsApp 验证信号

在为实时检测准备 CSV 或 TXT 名单时，第一步是确定哪种账户存在信号支持您的特定工作流程。WA Lookup 提供三种不同的服务类型，均通过同一组同步接口访问。service_type 参数控制响应中返回的字段。

基础注册检查 (ws)

ws 服务类型用于确认提交的电话号码当前是否已在 WhatsApp 上注册。此检查返回一个 registered 字段，提供直接的账户存在信号。它为内部决策提供参考，帮助确定您的 CSV 或 TXT 文件中的哪些号码在检查时关联了平台账户存在信号。

头像丰富化检查 (ws_avatar)

ws_avatar 服务类型包含基础注册检查，并增加了个人资料丰富化功能。除了 registered 状态外，此检查还会返回一个指示头像可用性的 avatar 布尔值和一个 avatar_url 字符串；没有可用地址时为空字符串。在审查用户资料时，此额外背景信息可作为其他检查之外的参考输入。

商业账户检查 (ws_business)

ws_business 服务类型在检查 WhatsApp 注册的基础上，识别该账户是否使用 WhatsApp Business。它返回一个 business 布尔值。此信号有助于团队通过区分标准账户和商业资料来细分列表，从而支持更具针对性的工作流程路由。

准备数据文件

把 CSV 或 TXT 名单交给实时检测处理，最关键的要求是正确的数据格式。WA Lookup 要求所有号码必须以 E.164 格式提交。E.164 是一种国际电话编号计划，为每个设备分配一个全球唯一的标识符。

要准备您的 CSV 或 TXT 文件：

1. 包含国家代码： 每个号码必须以相应的国际国家代码开头。
2. 移除格式字符： 从列表中剔除空格、连字符、括号以及任何其他非数字字符。
3. 省略前导零： 移除不属于国际拨号代码的任何本地中继前缀（通常是开头的零）。

例如，美国号码应格式化为以国家代码（例如 1）开头的连续数字字符串。确认您的整份名单符合 E.164 标准有助于避免在同步检查过程中出现格式错误。一个干净、标准化的输入文件对于检索每个提交号码的准确账户存在信号至关重要。

提交名单进行验证

一旦您的 CSV 或 TXT 名单格式正确，就可以将标识符提交给 WA Lookup 平台。主路径是同步的：结果在与请求相同的 HTTP 响应中返回，而不是稍后交付。

对于集成该服务的技术团队，单个号码使用 POST /api/v1/check，最多 100 个号码使用同步多号接口 POST /api/v1/batch-check。两种请求都需要 X-API-Key 和 Content-Type: application/json 标头；单号请求体包含 service_type 和 identifier，多号请求体包含 service_type 和 identifiers。请按照 API 文档在客户端控制并发。远超一次实时请求的整份 CSV 或 TXT 文件，也可以作为异步批量任务上传；提交时要选定号码所属的国家或地区，一份名单应基本属于这一个国家。

失败、超时或无法判定的检测不会保留扣费；当前计费规则请以价格页为准。

解读结果

对于完成的 WhatsApp 检测，返回的 data 包含 service_type、identifier 和 registered；ws_avatar 另有 avatar 与 avatar_url，ws_business 另有 business。内部记录、交易、状态和计费字段不会对外返回。

registered 结果报告了在检查那一刻可用的 WhatsApp 状态字段。了解此账户存在信号的边界非常重要。

此外，验证过程不会报告在线状态、消息历史记录或联系人同意情况。它也不会指示该号码是否可以成功联系或消息是否会被送达。该信号仅用于向您的内部数据库告知平台注册情况，在组织 CRM 或路由记录时，它可以作为其他检查之外的参考输入。

常见问题解答

电话号码所需的格式是什么？

所有电话号码必须严格以 E.164 格式提交。此国际编号计划要求包含国家代码，并移除所有非数字字符、空格和本地前导零。

我可以对整份名单检查 WhatsApp Business 状态吗？

可以，通过选择 ws_business 服务类型，您可以同时检查基础注册状态以及该账户是否使用 WhatsApp Business。无论是单号检测还是同步多号请求，都会返回一个指示商业账户存在情况的布尔值。

如果检查失败会怎样？

失败、超时或无法判定的检测不会保留扣费；当前计费规则请以价格页为准。

验证结果是异步交付的吗？

主路径不是。同步单号与多号接口都在与请求相同的 HTTP 响应中返回完成结果。整份大名单另有异步批量任务（上传、等待、下载）作为补充，但日常检测直接走同步接口即可。