Creare una verifica di numeri WhatsApp (API)

Verifica se un elenco di numeri di telefono è registrato su WhatsApp prima di inviare loro messaggi. Usala per ripulire elenchi di contatti importati, convalidare i numeri in fase di registrazione o rimuovere numeri a cui l'invio fallirebbe comunque.

La richiesta crea un'attività di verifica e restituisce subito un campaign_id. I numeri vengono poi controllati in background da uno dei tuoi numeri WhatsApp collegati. Usa il campaign_id con Stato della verifica per seguire l'avanzamento, oppure con Risultati della verifica per leggere i risultati.

Esempio rapido#

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');
}

Sostituisci YOUR_API_KEY con una chiave da Impostazioni → Chiavi API. La chiave determina a quale spazio di lavoro appartiene l'attività.

Parametri della richiesta#

Risposta#

Una richiesta riuscita restituisce HTTP 200:

{
  "status": "success",
  "message": "Verification task created successfully",
  "campaign_id": 4521,
  "numbers_count": 3,
  "numbers_submitted": ["919876543210", "919876543211", "14155550123"]
}

Ogni numero accettato parte come pending. L'attività compare anche nella pagina Verifica Numero della tua dashboard. Lì la sua scheda può continuare a mostrare Elaborazione anche dopo il completamento, quindi usa Stato della verifica per lo stato reale.

Errori#

Gli errori restituiscono un corpo JSON con status impostato su "error" e un codice di errore HTTP:

{ "status": "error", "message": "No valid phone numbers found" }

Come vengono verificati i numeri#

1. L'attività viene messa in coda

   L'API salva ogni numero accettato come pending e risponde immediatamente.

2. Un numero WhatsApp collegato li verifica

   I numeri vengono verificati fino a 10 alla volta usando un numero WhatsApp collegato nelle Impostazioni WhatsApp. Ogni numero diventa verified se è registrato su WhatsApp, oppure invalid se non lo è. Le verifiche vengono eseguite solo su un numero collegato che non è occupato a inviare messaggi, quindi durante una campagna di grandi dimensioni possono restare in attesa finché l'invio non termina.

3. Leggi i risultati

   Interroga periodicamente Stato della verifica finché overall_status non è completed, poi leggi i numeri dalla stessa risposta o da Risultati della verifica.

Suggerimenti#

• Includi sempre il prefisso internazionale. Un numero locale di 10 cifre senza prefisso supera il controllo sulla lunghezza, ma viene verificato esattamente come è scritto, quindi il risultato non riguarderà il numero che intendevi.
• Non usare il prefisso internazionale 00. Viene rimosso un solo 0 iniziale, quindi 00919876543210 viene verificato come 0919876543210. Invia 919876543210.
• Rimuovi tu stesso i duplicati prima di inviare, così non consumi con le ripetizioni il limite per richiesta del tuo piano.
• Controlla numbers_submitted per trovare i numeri esclusi perché troppo corti o contenenti lettere.
• Elenchi grandi: se raggiungi il limite per richiesta, invia più attività più piccole e tieni traccia di ogni campaign_id.

Nuovo alla verifica dei numeri? Consulta la guida alla verifica dei numeri.