Crear una verificación de números de WhatsApp (API)

Comprueba si una lista de números de teléfono está registrada en WhatsApp antes de enviarles mensajes. Úsala para limpiar listas de contactos importadas, validar los números de registro o eliminar números que solo darían error.

La solicitud crea una tarea de verificación y devuelve un campaign_id de inmediato. Después, uno de tus números de WhatsApp conectados comprueba los números en segundo plano. Usa el campaign_id con Estado de la verificación para seguir el progreso, o con Resultados de la verificación para leer los resultados.

Ejemplo rápido#

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

Sustituye YOUR_API_KEY por una clave de Configuración → Claves API. La clave determina a qué espacio de trabajo pertenece la tarea.

Parámetros de la solicitud#

Respuesta#

Una solicitud correcta devuelve HTTP 200:

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

Todos los números aceptados empiezan como pending. La tarea también aparece en la página Verificación de Números de tu panel. Su tarjeta puede seguir mostrando Procesando... después de terminar, así que usa Estado de la verificación para conocer el estado real.

Errores#

Los errores devuelven un cuerpo JSON con status con valor "error" y un código de error HTTP:

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

Cómo se comprueban los números#

1. La tarea se pone en cola

   La API guarda cada número aceptado como pending y responde de inmediato.

2. Un número de WhatsApp conectado los comprueba

   Los números se comprueban de 10 en 10 como máximo usando un número de WhatsApp conectado en la configuración de WhatsApp. Cada número pasa a verified si está registrado en WhatsApp, o a invalid si no lo está. Las comprobaciones solo se ejecutan en un número conectado que no esté ocupado enviando mensajes, así que durante una campaña grande pueden esperar hasta que termine el envío.

3. Lees los resultados

   Consulta periódicamente Estado de la verificación hasta que overall_status sea completed y luego lee los números en esa misma respuesta o en Resultados de la verificación.

Consejos#

• Incluye siempre el código de país. Un número local de 10 dígitos sin él supera la comprobación de longitud, pero se comprueba tal cual está escrito, así que el resultado no corresponderá al número que querías.
• No uses el prefijo internacional 00. Solo se elimina un 0 inicial, así que 00919876543210 se comprueba como 0919876543210. Envía 919876543210.
• Elimina tú mismo los duplicados antes de enviar, para no gastar en repeticiones el límite por solicitud de tu plan.
• Revisa numbers_submitted para encontrar los números que se descartaron por ser demasiado cortos o contener letras.
• Listas grandes: si alcanzas el límite por solicitud, envía varias tareas más pequeñas y haz seguimiento de cada campaign_id.

¿Es tu primera vez con la verificación de números? Consulta la guía de verificación de números.