WhatsApp 头像批量查询：如何选择多号码查询与批量任务
了解如何为多个号码查询 WhatsApp 头像：何时使用同步多号码查询，何时切换至批量任务，以及如何解读查询结果。
本文介绍如何一次性分析多个号码的公开 WhatsApp 头像，涵盖从列表准备到解读有序结果及批量 CSV 输出的全过程。
WhatsApp 头像批量查询工具旨在分析列表中每个号码对应的公开显示图片，并汇总返回结果。在 AvatarLookup 中，有两种实现路径。同步多号码查询支持在每个 API 请求中处理 1 到 100 个 WhatsApp 号码，并按相同顺序返回结果；控制台则支持最多 500 个号码，并逐一进行处理。对于更大规模的列表，异步的 WhatsApp 批量产品支持通过 TXT 或 CSV 文件提交，并为每个任务返回一个 CSV 文件。在这两种路径中，生成的查询结果仅代表分析已完成，并不代表该账号一定存在。
WhatsApp 头像批量查询应具备的功能
搜索该主题时，大多数工具最终都只是号码验证器：它们仅报告号码是否出现在 WhatsApp 上便停止了。另一些则是通过您自己的账号驱动 WhatsApp Web 的浏览器扩展程序，这会引发关于权限和账号安全的问题。很少有工具能解释如何处理图片本身。
AvatarLookup 中的显示图片查询即为头像解析。对于每个号码，该服务会查看其公开的 WhatsApp 头像，并返回特定于来源的公开头像字段以及图片类型等外观估计值，以便联系人数据团队能够识别哪些记录带有头像、徽标、插图或没有公开图片。
可见性取决于账号所有者。WhatsApp 的 隐私设置 允许用户将头像设置为向所有人、仅联系人、除某些联系人外的联系人或无人可见。查询结果仅反映查询时刻的公开状态，因此缺失图片是关于公开可见性的陈述，而非关于账号本身的陈述。
根据列表规模选择路径
| 列表情况 | 路径 | 结果获取方式 |
|---|---|---|
| 少量号码需手动查看 | 控制台，单次或多号码 | 在屏幕上逐个显示 |
| 最多 500 个号码，分析师驱动 | 控制台多号码 | 在控制台中逐个处理 |
| 代码调用，每批 1 到 100 个号码 | API 多号码 (POST /api/v1/batch-check) | 每个请求返回一个有序的 JSON 结果 |
| 大规模导出或定期文件 | WhatsApp 批量任务 (POST /api/v1/bulk-tasks) | 任务完成后返回一个 CSV 文件 |
当工作流需要在同一请求内获取答案时（例如审查界面或每晚处理数千个号码的定时任务，每次切分为 100 个），多号码查询是合适的选择。每个请求必须包含单一服务类型，因此请勿在同一调用中混合使用 WhatsApp 号码和电子邮件地址。
当列表规模较大，以至于将其切分为多个同步调用变得难以调度和重试时，请切换至批量产品。批量任务有其各自的每产品限制（详见 API 文档），因此在规划运行前请检查当前限额。
来自中国大陆 (+86)、香港 (+852) 和澳门 (+853) 的号码应使用实时单次查询，而非批量文件。
准备号码列表
整洁的输入是优化任何多号码查询最有效的方法。在发送任何数据之前：
- 将每个号码标准化为国际格式，包含国家代码，并去除空格、括号、连字符和分机说明。
- 去除重复项，因为同一个号码常以多种格式出现。
- 保留您自己的记录键，以便在结果返回时无需猜测即可与原始列表对应。
- 按路径拆分：每个 API 多号码请求最多 100 个号码，或为批量任务准备单个文件。
批量文件有更严格的规则。请使用 TXT 或 CSV 格式，每行一个号码，以国家代码开头的数字形式书写，不带加号或空格。为任务选择一个国家/地区；列表应基本属于该国家/地区。在多部分批量提交中，国家/地区字段必须位于文件字段之前。不支持 XLSX 等电子表格格式，请先导出为 CSV。
请保留您发送的精确文件或请求主体的副本。当结果出现异常时，输入数据是首要排查点。
解读有序结果
API 多号码查询按输入顺序返回结果，这使得数据合并变得简单：答案中的第一个位置对应请求中的第一个位置。请根据位置进行合并，并与您存储的列表进行核对，而不是从答案中重新解析号码。
每项结果都带有是否已生成分析的指示。当结果为正向时，表示该号码的分析已完成，且头像字段存在。这并不确认账号一定存在。当结果为负向时，表示号码无效、查询无法判定或查询失败。这并不代表账号不存在或没有图片。
请在您的数据模型中区分以下三种结果：
- 存在头像：已找到并描述了公开图片。
- 无头像：查询已完成，但没有公开图片可用。这是一个已完成的查询结果，且会产生费用。
- 无结果：输入无效、无法判定或失败。请检查输入并决定是否稍后重试。
批量任务会生成特定于 WhatsApp 的 CSV 文件。请阅读其标题并明确映射每一列，不要重复使用为其他产品编写的映射。
批量查询路径的操作步骤
WhatsApp 批量产品是异步的，因此工作流分为四个阶段：
- 提交准备好的文件和国家/地区至 POST /api/v1/bulk-tasks。响应将为您提供一个可供轮询的任务。
- 轮询 GET /api/v1/bulk-tasks/{id}，频率不超过每 30 秒一次。对于大型文件，较慢的间隔是合适的；不承诺固定的完成时间。
- 下载任务成功后的单个 CSV 文件。下载链接有效期为 12 小时；如果链接过期，请再次查询同一任务以获取新链接。
- 加载并核对 CSV 与您的源列表，并在每一行记录分析日期。
控制台用户无需代码即可遵循相同思路：上传文件，等待任务完成，然后下载 CSV。无论使用哪种路径，请将外观输出存储为算法估计值，并将公开头像数据视为联系人数据质量信号，而非身份验证。
常见问题解答
团队如何使用多号码查询处理 5,000 个号码的列表？
将列表拆分为最多 100 个号码的请求，按顺序或以适度的并行度发送，并按位置合并每个有序答案。为每个分片存储请求引用和时间戳，以便可以单独重新发送失败的分片。如果任务规模增长或成为定期导出任务，请迁移至 WhatsApp 批量产品，该产品可处理单个文件并返回一个 CSV。
WhatsApp 显示图片应该多久重新查询一次？
图片和隐私设置会发生变化，因此每个结果都是查询时刻的快照。当记录即将用于审查、图片对决策至关重要，或按照联系人数据的更新频率进行定期查询时，请重新查询。请保留带有日期的早期结果，而不是覆盖它们，以便审查人员查看变化情况。
电子邮件地址可以包含在同一个多号码请求中吗？
不可以。每个 API 多号码请求仅支持一种服务类型。受支持的 Gmail、Yandex 和 Mail.ru 地址使用邮箱头像解析路径，因此请先按标识符类型拆分混合列表，并分别发送 WhatsApp 号码和电子邮件地址请求。同样的拆分原则也适用于批量文件，每个任务仅属于一个特定的批量产品。
了解更多
选择符合您工作流下一步的产品信息。