WhatsApp批量验证API怎么接：从名单清洗、异步提交到CRM回写

假设你手上有一份刚从 CRM 导出的联系人名单，约 8 万条，来自巴西、印尼、英国等多个国家。号码格式很乱，有的带国家码，有的以 0 开头，还有的夹着空格和括号。你要做的是查清哪些号码开通了 WhatsApp、账号状态如何，再把结果写回 CRM。

结论是：这类名单用异步批处理来做，不要逐条同步请求。处理顺序如下：

1. 把号码统一成 E.164 格式，然后去重；
2. 按国家拆成批次；
3. 确定每批要查哪些字段；
4. 通过 REST API 提交任务，保存任务 ID；
5. 用 Webhook 接收结果；
6. 按有效组和无效组增量回写 CRM。

下面逐步说明每一步要注意什么。

先说一个前提：为什么不直接用 Meta 官方接口

很多开发者会先去 Meta 的 WhatsApp Business 接口里找「批量查号码是否注册」的端点，但找不到。官方 Cloud API 是为业务消息收发设计的，号码相关接口管理的是你自己企业账号下的电话号码，不提供对存量名单做批量开通状态筛选的功能。

所以，名单的开通状态检测通常作为一个独立的数据清洗步骤，放在 CRM 数据流水线里完成。它与后续怎么使用这些联系人是两件事，本文只讲前者。

第一步：E.164 标准化，然后再去重

批量验证接口通常要求号码符合 ITU-T E.164 格式：国家代码 + 国内号码，不带本地前导零、空格、短横线或括号，数字总长度不超过 15 位。

几个常见转换示例：

• 英国 07700 900123 转为 +447700900123，去掉本地前导 0，加上 44；
• 印尼 0812-3456-7890 转为 +6281234567890；
• 已经是 +55 (11) 91234-5678 的号码，只需去掉空格、括号和横线。

清洗时注意以下几点：

• 原始值单独保留一列，不要覆盖。标准化后的号码另存为 e164 字段，出问题时可以回溯。
• 先标准化，再去重。 0812... 和 +62 812... 在原始数据里是两条，标准化后是同一个号码。如果先去重，这类重复会漏掉。按条计价的服务会对重复号码重复计费。
• 缺国家码的号码不要猜。 如果 CRM 里有国家或地区字段，可以按它补国家码。补不出来的号码单独放一组，人工确认后再提交。混在批次里只会增加解析失败的数量。
• 阿根廷、墨西哥等国家的移动号码有特殊编码规则，转换逻辑可以参考 WhatsApp E.164格式转换规则。

第二步：按国家拆批次

即使接口允许单批不限量，多国名单也建议按国家分开提交，理由有三点：

• 各国号码的长度和前缀规则不同，分开处理更容易发现某个国家的清洗规则写错了；
• 结果通常要按市场分析，按国家分批后，回写和统计都更直接；
• 某批失败率异常时，可以直接定位到具体国家，不用在 8 万条里排查。

如果还不确定某个国家的号码格式，或者该市场主要用哪个平台，可以先查 NexCheck 区域方案页，再决定这个国家的批次是否要跑 WhatsApp 检测。

第三步：决定查到哪一层

检测结果一般分两层：

• 号码基础层：号码本身是否有效，例如空号、设备类型（移动、固话、VoIP 等）、高风险号。
• 平台属性层：号码是否开通 WhatsApp、账号是否封禁，以及注册时间、活跃情况、性别年龄等可获取的属性。

在 NexCheck 上，这两层分别对应号码基础检测和平台检测。检测项按条计价，不同平台能查的字段也不一样。WhatsApp 当前能查哪些项、每项单价是多少，请以 WhatsApp 平台页 的价目表为准。

怎么选字段，取决于这份名单接下来的用途：

• 只想判断号码能否作为 WhatsApp 联系方式保留，查开通状态就够了；
• 要给联系人分层，比如区分长期不活跃的号码，再加活跃等字段；
• 名单来源杂、空号可能比较多，可以先跑一遍基础检测，把明显无效的号码剔除，再对剩下的号码做平台检测，以减少费用。

两层检测的区别和结果合并方法，可以参考 WhatsApp筛号和号码验证有什么区别。

第四步：异步提交任务

几万到几百万条号码，不适合放在一个同步 HTTP 请求里等结果，连接很容易超时。常见做法是异步批处理：

1. 调用端通过 REST API 提交一个批次，服务端返回任务 ID；
2. 本地记录任务 ID 与批次号、国家、提交时间、号码数量的对应关系；
3. 检测完成后，服务端通过 Webhook 把结构化结果推送到你的接收地址。

接收 Webhook 的一端有几条通用做法值得遵守：

• 先返回成功，再处理数据。 收到推送后先把原始报文写入队列或落库，再立即返回 2xx，入库、回写等逻辑放到异步处理里。
• 按「任务 ID + 号码」做幂等处理。 同一结果被推送两次时，不应在 CRM 里产生两条更新。
• 做安全校验。 如果文档提供了签名或密钥校验方式，接收端应当校验，不要接受来源不明的推送。
• 对账。 定期检查已提交但一直没有收到回推的任务，按站内文档说明的方式跟进，不要默认它已经完成。

具体的请求参数、回推字段和鉴权方式，请以 NexCheck 站内文档为准，从官网导航的「筛号工具」注册后即可查看。完整的对接流程见 WhatsApp筛号API怎么接入，报错排查见 WhatsApp筛号失败原因怎么排查。

另外，并不是所有场景都需要接 API。一次性清理一份名单，在控制台上传 txt 或 csv、按有效和无效分组导出，通常更省事。线索持续进入 CRM、需要定期复检，或者要把检测结果自动写回系统时，才值得接入 API。

第五步：解读结果时注意这些边界

结果返回后，按有效组和无效组分流之前，先确认几个容易误读的地方：

• 「未开通」和「已封禁」是两种不同的状态。 前者是号码没有注册 WhatsApp，后者是账号存在但被平台限制。两者在 CRM 里应该用不同的值表示，不要合并成一个「无效」。
• 字段没有返回，不等于「否」。 注册时间、活跃情况等属性可能受平台隐私设置或可见性调整影响而无法获取。这类情况应记为「未知」，不要记成「不活跃」。
• 运营商字段和 WhatsApp 状态可能对不上。 在支持携号转网的国家，基础层的运营商归属和号码当前实际使用的情况可能存在时间差。两个字段冲突时，按各自的含义分别使用，不要互相覆盖。

各字段的具体含义，可以参考 WhatsApp筛号结果怎么看。

第六步：回写 CRM

回写时最常见的问题是：去重之后，一个号码可能对应多条 CRM 记录。比如同一个联系人被市场部和销售部各录了一次。所以第一步清洗时，就要保存「e164 → CRM 记录 ID 列表」的映射，回写时把结果分发到每一条对应的记录上。

建议在 CRM 里新增几个独立字段，不要把检测结果塞进备注里：

回写时遵循以下原则：

• 增量更新：只更新本次有结果的字段，空值不要覆盖旧值；
• 无效号码归档隔离，不直接删除：保留记录和检测时间，方便日后复检或核对；
• 保留检测时间：号码状态会变化，距离上次检测较久的记录，下次使用前可以重新跑一遍。

合规边界

批量验证只应该用于你合法持有的名单，比如自有的存量客户或客户主动留下的联系方式。名单的来源和用途是否合法，由名单持有方负责。检测服务只在任务范围内处理这些数据。不要尝试通过自建脚本绕过平台的隐私设置来获取信息。

下一步

如果名单已经按上面的步骤完成清洗和分批，下一步是到 WhatsApp 平台页 确认当前可查的检测项和单价，再决定每个批次查到哪一层。确定之后，在官网「筛号工具」注册，就可以在站内文档里获取 API 的接入说明；如果不打算接 API，也可以直接在控制台上传文件完成第一批检测。