注册并联系客服，免费领取 100 次检测。免费注册
WA Lookup
WA Lookup 工作流示意图：WhatsApp Lookup API：实时注册检测详解
本文所述工作流的示意图（WA Lookup）。

了解 WhatsApp Lookup API 如何处理同步实时注册检测、响应解析以及高并发工作流，从而构建整洁的通信管道。

WA Lookup API 提供同步实时验证功能，可在查询时确认电话号码是否已注册 WhatsApp。通过查询专用的 REST 端点，团队可在发起的 HTTP 响应中立即获得账号存在状态信号。该架构支持单号码检测和同步批量请求，有助于组织清理路由队列、保护投递工作流并避免向未分配的号码发送消息。

理解 WhatsApp 注册信号

注册检测用于评估特定标识符在检测时是否在平台上拥有账号。此平台存在信号在发起通信前提供了技术上的触达背景。

电话号码必须遵循 ITU-T Recommendation E.164 中描述的国际公共电信格式，该格式要求包含国家代码且长度限制为 15 位数字。以 E.164 结构评估号码可标准化跨国际系统的数据输入。

从运营角度来看，注册数据用于指导受众路由，而非确立身份、线路所有权或接收者同意。进行商业外联的组织必须保留单独的加入许可记录，以遵守 WhatsApp Business Messaging Policy。将账号存在检测与 GDPR Article 5 (Regulation (EU) 2016/679) 中的数据最小化要求保持一致，可确保系统仅处理投递工作流所需的技术触达指标。

同步实时验证工作流

WhatsApp Lookup API 提供了专为即时、内联决策管道设计的同步端点。由于这些端点以同步方式运行，发起的 HTTP 请求会直接在响应负载中接收验证属性，无需二次轮询周期。

单号码检测

对于注册表单或单条线索录入等事务性事件，集成程序使用 X-API-Key 身份验证标头调用 POST /api/v1/check。请求需提交 E.164 格式的电话字符串并选择目标服务类型。

同步批量检测

当工作流需要同时验证较小的队列时，POST /api/v1/batch-check 支持在单次调用中接收最多 100 个电话号码。该端点会同步评估整个批次，并在发起的响应中返回统一的结果集。

管理请求量的开发者应查阅官方文档以了解用户并发和超时参数，因为平台通过并发控制而非固定的每分钟请求上限来管理容量。

实时服务检测类型对比

Lookup API 将注册查询结构化为三种特定的实时服务类型，以支持不同的风险和丰富化需求。

服务类型 服务名称 记录的功能 返回的数据字段
ws WhatsApp 注册检测 评估平台注册状态 registered
ws_avatar WhatsApp 头像检测 评估注册状态、头像存在情况、头像链接 registered, avatar, avatar_url
ws_business WhatsApp 商业账号检测 评估注册状态、WhatsApp 商业账号标识 registered, business

选择 ws 可提供核心触达指标。对于需要资料丰富化的工作流，ws_avatar 会在可访问时附加头像可用性及托管图像链接。ws_business 选项可识别注册电话是否在 WhatsApp 商业平台上运行，从而支持消费者账号与商业账号之间的细分。

解读状态码与余额消耗

公共 API 响应使用包含 code、msg 和 data 的标准信封字段来格式化已完成的检测。正确解析已决定的结果与服务错误，对于可靠的数据管道至关重要。

已完成的检测会产生一个成功响应码，并包含 data.registered（设置为 true 或 false）。已决定为 true 和已决定为 false 的记录均代表已完成的查询，并会相应地消耗余额。

不确定状态或上游服务中断会返回非零业务代码，而不是 registered=false 值。下游系统应隔离非零代码以进行重试逻辑，而不是将其视为未分配的电话号码。注册用户可联系支持团队获取 100 次免费检测额度，以验证开发环境中的响应处理情况。

用于列表处理的异步批量任务

虽然同步端点可处理实时客户交互，但大规模数据迁移需要异步工作流。对于基于文件的验证，团队可使用 POST /api/v1/bulk-tasks 提交数据集，并使用 GET /api/v1/bulk-tasks/{id} 跟踪处理进度。

批量任务文件必须以 TXT 或 CSV 文档形式提交，且每行包含一个电话号码。文件必须专注于单一国家/地区目的地，因为包含 10% 或更多非目标国家/地区号码的列表会触发预检拒绝。产品特定的文件限制适用，团队应查阅官方文档以了解当前的文件大小规则。

区域覆盖范围在不同工作流之间也有所不同。实时单号码检测支持中国大陆 (+86)、香港 (+852) 和澳门 (+853) 的号码（低容量），而异步批量文件任务则排除这些目的地。台湾地区的覆盖范围在所有处理模式下均未确认。

常见问题解答

实时同步检测与异步批量任务有何区别？

实时检测将号码直接提交至 POST /api/v1/check 或 POST /api/v1/batch-check，并在同一 HTTP 响应中立即交付结果。异步批量任务通过 POST /api/v1/bulk-tasks 接收格式化文件，首先返回任务 ID，并在处理完成后生成可下载的结果 CSV。

API 如何处理不确定检测的费用？

已注册和未注册的已完成评估均会产生标准检测费用。相比之下，不确定或服务错误的结果会返回非零状态码而非 false 结果，且失败的检测不会消耗余额。

了解更多

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

参考来源