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 字符串；没有可用地址时，avatar_url 为空字符串。

请求契约

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

始终返回的响应字段

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

ws_avatar 新增的两个字段

选择 service_type=ws_avatar 会增加一个 avatar 布尔值和一个 avatar_url 字符串。avatar 布尔值用于报告是否检测到头像。成功的 ws_avatar 响应始终包含 avatar_url 字段；没有可用地址时，该字段为空字符串。请将它与 avatar 分开处理，因为两个字段表达的是不同信息。

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

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

常见问题解答

应该如何处理 avatar_url？

成功的 ws_avatar 响应始终包含 avatar_url 字段。没有可用地址时按空字符串处理；不要用它替代 avatar 字段。

identifier 需要什么号码格式？

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

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

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