集成 WA Lookup API 以实现 WhatsApp 个人资料丰富化

本技术指南旨在帮助开发者通过 WA Lookup API 实现同步的 WhatsApp 个人资料和头像查询。

WA Lookup API 提供了一个同步 REST 接口，支持开发者自动化 WhatsApp 个人资料的丰富化流程。通过向 /api/v1/check 端点发送 POST 请求，并指定服务类型（ws、ws_avatar 或 ws_business）以及 E.164 格式的电话号码，API 可直接在 HTTP 响应中返回即时的账户存在信号。这些信号包括注册状态、头像可用性、头像 URL 以及商业账户标识，可作为 CRM 路由、受众细分和内部决策支持工作流的输入。

WA Lookup API 简介

在将通信渠道集成到业务工作流时，技术团队需要准确的账户存在信号来辅助其路由和细分逻辑。WA Lookup API 是一款单标识符 API，旨在确认提交的电话号码是否已注册 WhatsApp。 该 API 的主要功能是提供同步检查，并在与请求相同的 HTTP 响应中返回数据。这种同步架构支持开发者构建即时的决策支持机制，而无需处理异步 Webhook、轮询基础设施或异步任务队列带来的额外开销。 理解此账户存在信号的边界至关重要。注册结果仅反映检查时刻的 WhatsApp 状态字段。它不会报告在线状态、消息历史记录、用户同意情况，也不会检查该号码当前是否可以联系。相反，它有助于完善更广泛的工作流，帮助团队审查记录并根据平台存在情况优先处理外联工作。

理解服务类型

WA Lookup API 将其功能整合到一个同步端点中。开发者可以通过修改请求负载中的 service_type 参数来控制检索哪些特定的个人资料信号，以及适用哪种计费标准。该 API 支持三种不同的服务类型：

• WhatsApp 检查器 (ws)：这是基础服务类型。其范围仅限于确认提交的电话号码是否已注册 WhatsApp。它提供基本的平台注册信号。
• WhatsApp 头像检查器 (ws_avatar)：此服务类型在基础检查的基础上进行了扩展，提供个人资料丰富化功能。除了检查 WhatsApp 注册情况外，它还会检查头像的可用性，并返回 avatar_url 字段；没有可用地址时为空字符串。
• WhatsApp 商业检查器 (ws_business)：此服务类型专为 B2B 工作流设计。它在检查标准 WhatsApp 注册情况的同时，还会确定该账户是否使用 WhatsApp Business，从而提供特定的商业个人资料信号。

通过选择合适的服务类型，技术产品经理可以根据其具体工作流需求定制 API 输出，确保仅请求和使用其特定用例所需的数据。

技术实现

集成 WA Lookup API 需要遵守严格的 JSON 请求契约和格式规则。所有交互均通过 POST /api/v1/check 端点进行。 为了正确进行身份验证和格式化请求，开发者必须包含特定的标头：包含有效 API 密钥的 X-API-Key 标头，以及 Content-Type: application/json 标头。 请求的 JSON 正文必须包含两个字段：

1. service_type：字符串值，可选 "ws"、"ws_avatar" 或 "ws_business"。
2. identifier：目标电话号码，必须严格以 E.164 格式提交。

E.164 格式是一种国际电话编号计划，确保电话号码在全球范围内具有唯一性。E.164 格式的号码必须以加号 (+) 开头，后跟国家代码和用户号码，中间不含空格、破折号或括号（例如 +17253100591）。未能使用 E.164 格式将导致检查失败。 由于该 API 是完全同步的，因此在执行检查时 HTTP 连接保持打开状态，结果将在即时的 HTTP 响应中交付。

解读 API 响应

WA Lookup API 在每次检查响应中都会返回一组可预期的字段，并根据所选的 service_type 追加额外字段。 对于完成的 WhatsApp 检测，返回的 data 包含 service_type、identifier 和 registered；ws_avatar 另有 avatar 与 avatar_url，ws_business 另有 business。内部记录、交易、状态和计费字段不会对外返回。 当 service_type 设置为 ws 时，返回的响应仅包含 service_type、identifier 和 registered。 当 service_type 设置为 ws_avatar 时，响应模式会扩展为包含 avatar 字段（布尔值，指示是否设置了头像）和 avatar_url 字段。没有可用地址时，avatar_url 为空字符串。 当 service_type 设置为 ws_business 时，响应模式会添加一个 business 字段，这是一个布尔值，指示注册号码是否与 WhatsApp Business 账户关联。

仪表板与使用管理

API 使用情况的管理和工作流输入的监控通过平台仪表板进行。仪表板为 API 密钥管理提供全面支持，允许开发者安全地生成和轮换 X-API-Key 标头所需的密钥。 为了进行运营监督，仪表板包含跟踪余额、审查检查历史记录和访问产品级报告的功能。技术团队可以监控最近的检查、分析余额支出并查看账户使用情况，以了解其使用模式并优化集成。 可在网页后台查看余额和检测历史；具体计费规则请以价格页和 API 文档为准。

常见问题解答

WA Lookup API 是同步的吗？

是的。实时检测接口是同步的：结果在发起请求的同一次 HTTP 响应中返回。单号接口检测一个号码，同步多号接口最多接收 100 个号码；这两条链路都没有任务、回调或轮询流程。数量更大的名单由另一条异步批量产品处理，上传文件、稍后下载结果。

ws 和 ws_avatar 服务类型有什么区别？

ws 服务类型仅返回基本的 WhatsApp 注册信号。ws_avatar 服务类型返回注册信号，并额外检查头像的可用性，同时返回 avatar_url 字符串；没有可用地址时为空字符串。

电话号码应遵循什么格式？

提交给 API 的所有电话号码必须按照 E.164 标准格式化。这要求以加号 (+) 开头，后跟国家代码和用户号码，中间不含空格或特殊字符。