コンテンツへスキップ
Wbiztool

番号確認API

WhatsApp番号確認の作成(API)

メッセージを送る前に、電話番号のリストがWhatsAppに登録されているかどうかを確認します。インポートした連絡先リストの整理、登録時の番号の検証、送っても失敗するだけの番号の除外などに利用できます。

POSThttps://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"]
  }'

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はHTTP 500で失敗します。

レスポンス#

リクエストが成功すると、HTTP 200が返ります。

{
  "status": "success",
  "message": "Verification task created successfully",
  "campaign_id": 4521,
  "numbers_count": 3,
  "numbers_submitted": ["919876543210", "919876543211", "14155550123"]
}
フィールド説明
statusstring"success"。エラーの場合は"error"が返ります。
messagestringVerification task created successfully
campaign_idinteger確認タスクのID。番号確認のステータス番号確認の結果で使用します。
numbers_countinteger整形後に受け付けられた番号の数。
numbers_submittedarray of strings確認される整形済みの番号。送信した内容と比較すると、除外された番号がわかります。

受け付けられた番号はすべてpendingの状態から始まります。タスクはダッシュボードの番号確認ページにも表示されます。そこでのカードは完了後も「処理中」と表示され続けることがあるため、実際の状態は番号確認のステータスで確認してください。

エラー#

エラーの場合は、status"error"のJSONボディとHTTPエラーコードが返ります。

{ "status": "error", "message": "No valid phone numbers found" }
HTTPメッセージ対処方法
405Only POST method allowedPOSTリクエストを送信してください。
401API key requiredAuthorization: Bearer YOUR_API_KEYヘッダーを追加してください。
401Invalid API keyキーが存在し、削除または無効化されていないことを確認してください。
403Verification feature not available for your planご利用のプランには番号確認が含まれていません。プランをアップグレードしてください。
400Numbers array is requiredContent-Type: application/jsonを指定し、numbersを空でないJSON配列で送信してください。
400No valid phone numbers found整形後に10桁以上になった番号がありません。国コードを含めてください。
400Request contains N numbers but your plan allows only M verifications1回のリクエストに含められる番号の数はプランによって制限されています。リストを小さなリクエストに分割してください。
500Internal server error: …通常は、末尾のカンマなどが原因でJSONボディが無効になっています。

番号の確認の流れ#

  1. タスクがキューに登録される

    APIは受け付けたすべての番号をpendingとして保存し、すぐにレスポンスを返します。

  2. 接続済みのWhatsApp番号で確認される

    WhatsApp設定で接続されたWhatsApp番号を使って、番号が一度に最大10件ずつ確認されます。WhatsAppに登録されている番号はverified、登録されていない番号はinvalidになります。確認は、接続されていてメッセージ送信中でない番号でのみ実行されるため、大規模なキャンペーンの実行中は送信が終わるまで待機することがあります。

  3. 結果を取得する

    overall_statuscompletedになるまで番号確認のステータスをポーリングし、同じレスポンスまたは番号確認の結果から番号を読み取ります。

ヒント#

  • 必ず国コードを含める:国コードのない10桁のローカル番号は桁数チェックを通過しますが、記述されたとおりに確認されるため、意図した番号の結果にはなりません。
  • 国際プレフィックス00は使わない:先頭の0は1つしか削除されないため、009198765432100919876543210として確認されます。919876543210と送信してください。
  • 重複は送信前に自分で削除する:重複分でプランのリクエストあたりの上限を消費しないようにしましょう。
  • numbers_submittedを確認する:短すぎる、または文字を含んでいたために除外された番号を見つけられます。
  • 大きなリスト:リクエストあたりの上限に達する場合は、複数の小さなタスクに分けて送信し、それぞれのcampaign_idを追跡してください。

番号確認を初めて使う場合は、番号確認ガイドをご覧ください。