通过文件运行 WhatsApp 批量检测

本指南逐步介绍了异步 WhatsApp 批量检测任务，以及它们与实时检测的区别。

WhatsApp 批量检测是一项异步任务：您上传一个 TXT 或 CSV 列表，获取一个可跟踪的任务，在处理过程中等待，并在任务完成后下载结果文件。当列表规模远超实时请求的承载能力时，请使用此功能。对于需要即时响应的单个号码或小规模号码组，请改用实时检测。

何时使用批量文件检测

实时检测会在发起请求的同一响应中返回结果。这适用于注册表单、CRM 触发器或少量粘贴的号码组。批量文件检测则适用于相反的情况：导出的列表、购买或继承的数据库，或是对整个联系人表进行定期清理。

实际的区别在于工作流程，而非检测内容本身。实时检测会在响应中立即获得结果。而批量检测则是提交一次任务，系统会单独处理，随后您再获取输出结果。请将批量检测规划为定时任务，而非需要人工在屏幕前等待的操作。

目前有四种批量产品，每种产品对应一个信号：

每种产品都有各自的文件限制，因此在开始运行前，请阅读最新的 API 文档。请勿假设一种产品的限制适用于其他产品。

上传前准备文件

大多数批量运行失败或资源浪费的情况都源于输入文件。请先完成以下检查：

• 格式。 使用每行一个号码的 TXT 或 CSV 文件。不支持 XLSX 等电子表格格式，请导出为 CSV。
• 国际格式。 提供带有国家代码的完整号码，不要包含空格、括号或短横线。无法可靠解析不带国家代码的本地格式号码。
• 一国一文件。 列表应基本属于您选择的国家/地区。如果文件中包含大量其他国家的号码，预检阶段将会拒绝该文件，因此请先按国家拆分混合列表。
• 去重。 重复行会像其他行一样被计费，请提前删除重复项。
• 检查区域支持。 批量文件任务不支持中国大陆、香港或澳门的号码。这些地区仅支持有限的实时单号码检测。
• 许可。 在将文件用于外联之前，请确认您拥有联系这些人员的合法依据。

预检拒绝是一种有用的早期预警。它只会花费您几分钟时间，而不是在错误的文件上浪费运行额度。

提交任务并跟踪状态

您可以从仪表板或通过 API 提交批量任务。API 流程使用 POST /api/v1/bulk-tasks 创建任务，并使用 GET /api/v1/bulk-tasks/{id} 读取其状态。仪表板也会列出您的批量任务及其状态，这在由人工而非脚本运行作业时非常方便。

建议的常规流程如下：

1. 选择与您所需信号匹配的批量产品。
2. 上传准备好的文件并提交。
3. 保存提交时返回的任务引用。
4. 以适度的频率轮询状态或查看仪表板，而不是频繁请求接口。API 文档中描述了并发和超时控制；请查阅以了解当前的用法规则。
5. 任务完成后下载结果文件。

提交时会预扣余额。处理完成后，预扣余额中未使用的部分将退还至您的账户余额，任务失败则会释放全部预扣额。这是账单核对，而非普通检测的退款计划。无论号码是否已注册，已完成的结果均会扣费。

正确读取结果文件

可下载的结果文件是一个 CSV，每行对应一个已处理的号码。请将每一行视为运行时的信号：

• 已注册结果表示检测时账号存在。
• 头像或商业价值是对注册状态的补充。缺少头像并不意味着号码未注册，商业标志用于识别账号类型，而非验证公司身份。
• 无法判定的号码应在后续运行中重试，而不应直接视为未注册。

将文件加载回您的 CRM 或营销工具中，通过电话号码进行关联，并将检测日期存储在结果旁边。这样，细分就变成了简单的过滤器：将已注册的号码放入 WhatsApp 队列，其他号码则分配到不同渠道。

在工作流程中混合使用批量和实时检测

大多数团队最终会同时使用这两种方式。运行一次批量任务来清理现有数据库，然后对之后到达的每个新联系人使用实时检测。这样可以在不重复执行大型作业的情况下保持列表的实时性。两者都从同一个账户余额中扣除，因此一次充值即可覆盖仪表板、API 和批量任务。请参阅 定价页面 以获取当前的计划和余额详情。

常见问题解答

团队如何提交 WhatsApp 批量检测？

从仪表板上传准备好的 TXT 或 CSV 文件，或通过 API 创建任务，然后跟踪任务状态并在完成后下载结果文件。

为什么批量文件会在预检时被拒绝？

当文件中大量号码所属国家与所选国家不符，或号码缺少国家代码时，文件可能会被拒绝。在上传前按国家拆分列表可避免此问题。

批量任务后未使用的预扣余额会怎样？

余额在提交时预扣。处理后，任何未使用的部分都会退还至账户余额，任务失败则会释放全部预扣额。

批量检测与实时检测有何不同？

实时检测在同一响应中返回结果。批量检测先返回一个任务，单独处理文件，稍后再提供可下载的结果文件。

了解更多

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

• 查看产品文档 →
• 联系团队 →