集成 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 注册情况外，它还会检查头像的可用性。如果存在头像，且上游服务提供该信息，它将检索头像 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 格式的号码必须以加号 (+) 开头，后跟国家代码和用户号码，中间不含空格、破折号或括号（例如 +1234567890）。未能使用 E.164 格式将导致检查失败。 由于该 API 是完全同步的，因此在执行检查时 HTTP 连接保持打开状态，结果将在即时的 HTTP 响应中交付。

解读 API 响应

WA Lookup API 在每次检查响应中返回一组可预测的字段，并根据所选的 service_type 附加额外字段。 无论服务类型如何，每个响应都包含以下基准字段：

• id：特定检查的唯一标识符。
• identifier：提交的 E.164 电话号码。
• registered：核心账户存在信号，指示 WhatsApp 注册状态。
• transaction_id：交易的参考 ID。
• status：检查请求的结果状态。
• service_type：请求的服务类型（ws、ws_avatar 或 ws_business）。
• charged_amount_micros：该检查从账户余额中扣除的费用。 当 service_type 设置为 ws 时，响应仅包含 registered 字段以及基准交易数据。 当 service_type 设置为 ws_avatar 时，响应模式会扩展为包含 avatar 字段（布尔值，指示是否设置了头像）和 avatar_url 字段。avatar_url 是一个字符串，仅在上游服务成功提供时才会出现。 当 service_type 设置为 ws_business 时，响应模式会添加一个 business 字段，这是一个布尔值，指示注册号码是否与 WhatsApp Business 账户关联。

仪表板与使用管理

API 使用情况的管理和工作流输入的监控通过平台仪表板进行。仪表板为 API 密钥管理提供全面支持，允许开发者安全地生成和轮换 X-API-Key 标头所需的密钥。 为了进行运营监督，仪表板包含跟踪余额、审查检查历史记录和访问产品级报告的功能。技术团队可以监控最近的检查、分析余额支出并查看 7 天趋势，以了解其使用模式并优化集成。 该 API 采用按次付费的计费模式。为确保成本效益，失败或未确定的检查将自动退还至账户余额。对于评估 API 功能的团队，新账户可获得 $0.10 的试用余额，可用于注册、头像和商业账户检查。

常见问题解答

WA Lookup API 是同步的吗？

是的，WA Lookup API 是严格同步的。结果在与初始请求相同的 HTTP 响应中返回。该 API 不会异步交付结果，也不支持批量处理。

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

ws 服务类型仅返回基本的 WhatsApp 注册信号。ws_avatar 服务类型返回注册信号，并额外检查头像的可用性，在上游服务提供时返回头像 URL 字符串。

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

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