注册并联系客服，免费领取 100 次检测。免费注册
AvatarLookup
AvatarLookup 工作流示意图：WhatsApp 头像 API：基于电话号码的实时头像解析
本文所述工作流的示意图（AvatarLookup）。

本开发者指南旨在介绍 WhatsApp 头像 API：仅返回 URL 的工具与 AvatarLookup 的实时单次及同步批量 WhatsApp 头像请求有何区别，以及如何存储和重试结果。

WhatsApp 头像 API 通过电话号码获取其关联的公开头像信息。许多工具仅返回一个临时图片 URL，需要您自行下载并解读。AvatarLookup 的 WhatsApp 头像解析则返回结构化结果：通过 POST /api/v1/check 进行实时单次检查，或通过 POST /api/v1/batch-check 进行同步批量检查（每次请求 1–100 个号码）。结果中的外观属性均为算法估算值。系统仅分析公开头像，因此若联系人将照片权限设置为仅限联系人可见，则不会显示公开图片；对于“无法判定”的结果，应稍后重试，而不应将其视为对账户的最终结论。

三种 WhatsApp 头像 API 类型

针对此短语的搜索结果混杂了三种不同类型，选择错误的类型会浪费集成时间。

类型 功能 适用场景
官方商业资料设置 设置或读取您自己的商业账户照片；Meta 的个人资料照片设置参考涵盖了较旧的本地部署设置 您需要管理自己的商业号码
仅 URL 查询工具 返回其他号码公开照片的图片链接 您仅需展示图片
头像解析 返回关于公开头像的结构化结果，包括外观估算值 您需要存储字段并在列表中进行比对

官方商业设置仅用于您自己的账户照片，而非查询其他号码。仅 URL 工具返回的链接通常会过期，导致团队需要自行下载、存储和标记图片。头像解析则跳过了图片处理步骤，直接返回适合联系人记录的数据。这三种类型都受限于同一规则：照片必须是公开可见的。

使用 POST /api/v1/check 进行实时单次检查

当交互式流程（例如客服人员打开联系人记录）需要即时获取某一个号码的结果时，请使用单次检查。

  1. 标准化号码。 按照 ITU E.164 结构将其转换为包含国家代码的国际格式，并去除空格、连字符和括号。
  2. 发送已认证的请求 至 POST /api/v1/check，指定 WhatsApp 头像产品及号码。请遵循 API 文档中的确切请求体；切勿猜测字段名称。
  3. 读取并存储响应，同时记录检查日期和 WhatsApp 来源标签。
  4. 根据结果进行分支处理：存在头像、无头像或无法判定。

请将此调用置于客户等待的阻塞路径之外。如果检查缓慢或结果为“无法判定”，记录仍应保存，头像字段留空，并标记为待后续检查。中国大陆、香港和澳门的号码仅支持通过实时单次检查，因此请将其路由至此，而非批量文件。

使用 POST /api/v1/batch-check 进行同步批量检查

批量检查可在一次调用中处理短列表。每个请求接受 1–100 个同类型产品的标识符，并按发送顺序返回有序的 JSON 结果。

批量请求的实用规则：

  • 切勿混用产品。 在一个请求中发送 WhatsApp 号码，在另一个请求中发送支持的 Gmail、Yandex 或 Mail.ru 地址。
  • 依赖顺序，并进行核对。 结果遵循输入顺序；在写入数据库前，仍需将每个结果与对应的输入号码进行匹配。
  • 拆分长列表。 将 350 个号码的列表拆分为四个请求，每个请求最多 100 个。
  • 对大文件使用批量任务。 当列表规模更大时，异步 WhatsApp 批量产品可接受 TXT 或 CSV 文件，并返回一个 CSV 任务结果。

非技术团队可以使用仪表板，该功能最多接受 500 个标识符并逐一处理。无论哪种方式，仅 WhatsApp 和支持的邮箱域名提供实时和批量检查；Telegram、Viber、MAX、LINE 和 Zalo 仅支持批量产品。

处理“无法判定”和“无头像”结果

大多数集成错误源于将不同的结果合并为一个空值。请保持区分：

  • 已生成结果。 批量响应会标记每个已生成结果的项目。该标志意味着请求已获得结果，并不代表 WhatsApp 账户一定存在。
  • 未生成结果。 这涵盖了无效、无法判定或失败的项目。这并非针对账户或其头像的否定结论，因此请安排后续重试，而非删除联系人。
  • 无头像。 已完成的结果可能显示没有可用的公开图片。WhatsApp 的隐私设置允许用户将个人资料照片设置为“所有人”、“我的联系人”、“除我联系人以外的人”或“没有人”，因此缺少公开图片通常只是隐私选择。

将每种状态写入其对应的数值（例如：存在头像、无头像或重试），并记录重试原因。清晰的状态模型也能使报告更准确：仪表板上的“无头像”计数绝不应包含那些仅仅是“无法判定”的项目。

将结果存储为估算值

外观属性（如图片类型、年龄范围或发色）描述的是图片本身，而非号码背后的个人。卡通、宠物、标志或合影都可以是有效的个人资料图片，对其进行分析仍属于已完成的回答。

简单的存储模式：

字段 示例内容
来源 WhatsApp 公开头像
结果 存在头像、无头像或重试
图片类型估算 人像、非人类等
外观估算 存储在以估算命名的字段中
检查日期 请求日期

请勿将这些字段用于资格、信用、招聘或定价决策，也不要用于任何基于预估年龄或性别进行差异化对待的筛选。公开头像仅作为联系人数据信号；它不能验证身份、账户所有权或联系许可。请设置复核间隔，因为用户会更换图片，并根据您的正常保留策略删除陈旧的估算值。

常见问题解答

团队如何获取实际的图片文件，而不是解析字段？

头像解析旨在返回关于公开头像的结构化结果，而非作为图片下载器。如果工作流确实需要展示图片，请考虑其必要性以及文件的存储和删除方式。许多联系人数据工作流仅需确认是否存在公开头像及其类型，而解析结果已涵盖这些信息。

开发者应如何重试“无法判定”的 WhatsApp 检查？

将“无法判定”的号码收集到重试队列中，而不是在循环中立即重新发送。稍后通过单次或批量请求重新检查，并限制每个号码的尝试次数，以防持续失败导致无限循环。在最后一次尝试后，请将记录保留为“无法判定”，而不是将其转换为“无头像”，因为这些结果的含义不同。

团队如何检查已持有的图片，而不是电话号码？

请使用图片人像解析。它接受 JPEG、PNG、WebP 或 GIF 文件，并通过记录的图片人像端点进行多部分文件上传调用。它描述图片本身，返回图片类型和外观属性作为算法估算值，不涉及电话号码或账户。这适用于客户直接上传的图片，例如通过表单提交的个人资料照片。

了解更多

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

参考来源