番号確認API
WhatsApp番号確認の作成(API)
メッセージを送る前に、電話番号のリストがWhatsAppに登録されているかどうかを確認します。インポートした連絡先リストの整理、登録時の番号の検証、送っても失敗するだけの番号の除外などに利用できます。
https://wbiztool.com/api/v1/verification/create/リクエストボディ: JSON(application/json)
リクエストを送ると確認タスクが作成され、すぐにcampaign_idが返ります。その後、接続済みのWhatsApp番号のいずれかによって、バックグラウンドで番号が確認されます。campaign_idを番号確認のステータスで使うと進捗を追跡でき、番号確認の結果で使うと結果を取得できます。
クイック例#
curl -X POST https://wbiztool.com/api/v1/verification/create/ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"campaign_name": "Website leads - September",
"numbers": ["919876543210", "+91 98765 43211", "14155550123"]
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/verification/create/",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"campaign_name": "Website leads - September",
"numbers": ["919876543210", "+91 98765 43211", "14155550123"],
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 4xx or 5xx
if result["status"] == "success":
print("Task created, campaign_id", result["campaign_id"])
print("Accepted numbers:", result["numbers_submitted"])
else:
print(f"Failed ({response.status_code}):", result["message"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/verification/create/", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
campaign_name: "Website leads - September",
numbers: ["919876543210", "+91 98765 43211", "14155550123"],
}),
});
const result = await response.json(); // read the body even when the HTTP code is 4xx or 5xx
if (result.status === "success") {
console.log("Task created, campaign_id", result.campaign_id);
console.log("Accepted numbers:", result.numbers_submitted);
} else {
console.error(`Failed (${response.status}):`, result.message);
}<?php
$payload = [
'campaign_name' => 'Website leads - September',
'numbers' => ['919876543210', '+91 98765 43211', '14155550123'],
];
$ch = curl_init('https://wbiztool.com/api/v1/verification/create/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_KEY',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? '') === 'success') {
echo 'Task created, campaign_id ' . $result['campaign_id'];
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}YOUR_API_KEYは、設定 → APIキーにあるキーに置き換えてください。タスクがどのワークスペースに属するかは、キーによって決まります。
リクエストパラメータ#
ヘッダー
Authorizationheader必須Bearer YOUR_API_KEY。キーは有効で、削除されていない必要があります。このAPIではclient_idは不要です。Content-Typestring必須application/jsonにする必要があります。それ以外のContent-Typeではnumbersが読み取られず、Numbers array is requiredが返ります。
ボディ
numbersarray of strings必須確認する電話番号です。それぞれ国コード付きで指定します(例:インドの番号なら
919876543210)。確認の前に、各番号は次のように整形されます。- スペース、
+、-、括弧が削除されます - 先頭の
0が1つ削除されます - 結果は数字のみで、10桁以上である必要があります
条件を満たさない番号は、通知なく除外されます。重複は削除されないため、同じ番号はそれぞれ個別に確認されます。
- スペース、
campaign_namestring任意ダッシュボードでタスクを見つけるための名前です。省略した場合は、
API Verificationの後にサーバーのIST(UTC+5:30)での日時が付いた名前になります(例:API Verification 20260916_154500)。名前は500文字まで指定できます。nullは送信しないでください。500文字を超える名前やnullはHTTP500で失敗します。
レスポンス#
リクエストが成功すると、HTTP 200が返ります。
{
"status": "success",
"message": "Verification task created successfully",
"campaign_id": 4521,
"numbers_count": 3,
"numbers_submitted": ["919876543210", "919876543211", "14155550123"]
}
| フィールド | 型 | 説明 |
|---|---|---|
status | string | "success"。エラーの場合は"error"が返ります。 |
message | string | Verification task created successfully。 |
campaign_id | integer | 確認タスクのID。番号確認のステータスと番号確認の結果で使用します。 |
numbers_count | integer | 整形後に受け付けられた番号の数。 |
numbers_submitted | array of strings | 確認される整形済みの番号。送信した内容と比較すると、除外された番号がわかります。 |
受け付けられた番号はすべてpendingの状態から始まります。タスクはダッシュボードの番号確認ページにも表示されます。そこでのカードは完了後も「処理中」と表示され続けることがあるため、実際の状態は番号確認のステータスで確認してください。
エラー#
エラーの場合は、statusが"error"のJSONボディとHTTPエラーコードが返ります。
{ "status": "error", "message": "No valid phone numbers found" }
| HTTP | メッセージ | 対処方法 |
|---|---|---|
405 | Only POST method allowed | POSTリクエストを送信してください。 |
401 | API key required | Authorization: Bearer YOUR_API_KEYヘッダーを追加してください。 |
401 | Invalid API key | キーが存在し、削除または無効化されていないことを確認してください。 |
403 | Verification feature not available for your plan | ご利用のプランには番号確認が含まれていません。プランをアップグレードしてください。 |
400 | Numbers array is required | Content-Type: application/jsonを指定し、numbersを空でないJSON配列で送信してください。 |
400 | No valid phone numbers found | 整形後に10桁以上になった番号がありません。国コードを含めてください。 |
400 | Request contains N numbers but your plan allows only M verifications | 1回のリクエストに含められる番号の数はプランによって制限されています。リストを小さなリクエストに分割してください。 |
500 | Internal server error: … | 通常は、末尾のカンマなどが原因でJSONボディが無効になっています。 |
番号の確認の流れ#
タスクがキューに登録される
APIは受け付けたすべての番号を
pendingとして保存し、すぐにレスポンスを返します。接続済みのWhatsApp番号で確認される
WhatsApp設定で接続されたWhatsApp番号を使って、番号が一度に最大10件ずつ確認されます。WhatsAppに登録されている番号は
verified、登録されていない番号はinvalidになります。確認は、接続されていてメッセージ送信中でない番号でのみ実行されるため、大規模なキャンペーンの実行中は送信が終わるまで待機することがあります。結果を取得する
overall_statusがcompletedになるまで番号確認のステータスをポーリングし、同じレスポンスまたは番号確認の結果から番号を読み取ります。
ヒント#
- 必ず国コードを含める:国コードのない10桁のローカル番号は桁数チェックを通過しますが、記述されたとおりに確認されるため、意図した番号の結果にはなりません。
- 国際プレフィックス
00は使わない:先頭の0は1つしか削除されないため、00919876543210は0919876543210として確認されます。919876543210と送信してください。 - 重複は送信前に自分で削除する:重複分でプランのリクエストあたりの上限を消費しないようにしましょう。
numbers_submittedを確認する:短すぎる、または文字を含んでいたために除外された番号を見つけられます。- 大きなリスト:リクエストあたりの上限に達する場合は、複数の小さなタスクに分けて送信し、それぞれの
campaign_idを追跡してください。
番号確認を初めて使う場合は、番号確認ガイドをご覧ください。
