ws_avatar 服务类型：请求、响应及字段参考

WA Lookup 通过单一同步调用提供 WhatsApp 检查功能，service_type 的值决定了执行哪种检查。本文档是 ws_avatar 变体的字段级参考。

要使用 WA Lookup 进行 WhatsApp 头像检查，请发送 POST /api/v1/check 请求，并在请求头中包含 X-API-Key，JSON 请求体为 {"service_type": "ws_avatar", "identifier": "<E.164 格式号码>"}。响应将返回标准的检查字段，以及一个 avatar 布尔值；如果上游服务提供了头像，还会包含一个 avatar_url 字符串。

请求契约

WA Lookup 仅记录了一个同步调用，即 POST /api/v1/check，需携带 X-API-Key 请求头和 Content-Type: application/json。请求体包含两个固定值：service_type（用于选择检查类型）和 identifier（必须为 E.164 格式的电话号码）。以本地格式提交号码是导致可避免失败的最常见原因，因此请在发送前进行标准化处理。

始终返回的响应字段

每个 WA Lookup 检查响应都包含 id、identifier、registered、transaction_id、status、service_type 和 charged_amount_micros。registered 字段用于回答所提交的号码是否存在 WhatsApp 账户。transaction_id 和 charged_amount_micros 字段用于对账，因为它们将结果与计费记录关联起来。

ws_avatar 新增的两个字段

选择 service_type=ws_avatar 会增加一个 avatar 布尔值和一个 avatar_url 字符串。avatar 布尔值用于报告是否检测到头像。avatar_url 字符串仅在上游服务提供时才会出现，因此您的集成必须将其视为可选字段，而不能假设每个 avatar 为真的结果都伴随有该字段。avatar_url 缺失属于正常结果，而非错误。

所有数据在一次响应中返回

由于该调用是同步的，registered 和 avatar 字段会在与请求相同的 HTTP 响应中返回。无需存储作业标识符，也无需轮询状态路由，这使得集成过程仅需一次调用和一个错误处理路径。为轮询 API 编写的代码结构通常可以直接简化。

常见问题解答

当 avatar 为 true 时，avatar_url 是否总是存在？

不是。avatar_url 仅在上游服务提供时才会出现，因此请在您的数据模型中将其视为可选字段。

identifier 需要什么号码格式？

E.164。在提交前进行标准化处理可避免最常见的检查失败情况。

我需要第二次调用来获取注册状态吗？

不需要。ws_avatar 会在同一响应中同时返回 registered 字段和头像相关字段。