Mar 20, 2025 · 3 min read

WhatsApp 号码检测 — 通过平台或 API 批量检查 | CheckNumber.AI

通过 API 检测 WhatsApp 号码注册状态的步骤说明；含 curl、Python、Node.js 示例，批量任务模式，约 $1/万次。

WhatsApp 号码检测 API — 分步集成指南

大规模验证 WhatsApp 注册状态对 营销名单清洗、风控、线索打分与 CRM 数据校验 至关重要。本文说明如何接入 CheckNumber.AI 的 WhatsApp 批量验证 API，并提供 curl、Python、Node.js 示例。

工作原理

生产环境使用 批量任务：上传号码文件 → 轮询任务状态 → 下载结果，而不是对每个号码单独发起一次同步 HTTP。该模式可高效处理大规模验证。

官方参考：WhatsApp Checker — bulk registration.

提交任务

POST https://api.checknumber.ai/v1/tasks

参数	说明
`file`	`.txt` / `.csv`，每行一个 E.164 号码
`task_type`	`ws` — WhatsApp 注册检测

示例 — curl：

curl --location 'https://api.checknumber.ai/v1/tasks' \
--header 'X-API-Key: API-KEY' \
--form 'file=@"./numbers.txt"' \
--form 'task_type="ws"'

示例 — Python：

import requests

url = "https://api.checknumber.ai/v1/tasks"
headers = {"X-API-Key": "YOUR_API_KEY"}

with open("numbers.txt", "rb") as f:
    files = {"file": f, "task_type": (None, "ws")}
    response = requests.post(url, headers=headers, files=files)

print(response.json())
# Output: {"task_id": "xyz123", "status": "pending", "total": 1000}

示例 — Node.js：

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const form = new FormData();
form.append('file', fs.createReadStream('numbers.txt'));
form.append('task_type', 'ws');

axios.post('https://api.checknumber.ai/v1/tasks', form, {
  headers: {
    ...form.getHeaders(),
    'X-API-Key': 'YOUR_API_KEY'
  }
}).then(res => console.log(res.data))
  .catch(err => console.error(err.message));

查询任务状态

POST https://api.checknumber.ai/v1/gettasks

curl --location 'https://api.checknumber.ai/v1/gettasks' \
--header 'X-API-Key: API-KEY' \
--form 'task_id="TASK_ID"'

结果字段

字段	说明
`Number`	E.164 电话号码
`whatsapp`	`yes` / `no` — 是否注册 WhatsApp

常见错误与排查

错误	原因	处理
`400 Bad Request`	缺少 API Key 或文件格式无效	确认请求头含 `X-API-Key`；号码使用 E.164（如 `+41798284651`）
`401 Unauthorized`	API Key 无效	在控制台核对密钥
`413 Payload Too Large`	文件超过大小限制	分批上传；单文件最大约 50MB
`500 Server Error`	服务端临时故障	约 30 秒后重试