Criar uma verificação de números de WhatsApp (API)

Verifique se uma lista de números de telefone está registrada no WhatsApp antes de enviar mensagens para eles. Use-a para limpar listas de contatos importadas, validar números de cadastro ou remover números que só gerariam falhas.

A requisição cria uma tarefa de verificação e retorna um campaign_id imediatamente. Os números são então verificados em segundo plano por um dos seus números de WhatsApp conectados. Use o campaign_id com Status da verificação para acompanhar o progresso, ou com Resultados da verificação para ler os resultados.

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

Substitua YOUR_API_KEY por uma chave de Configurações → Chaves API. A chave define a qual espaço de trabalho a tarefa pertence.

Parâmetros da requisição#

Resposta#

Uma requisição bem-sucedida retorna HTTP 200:

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

Todo número aceito começa como pending. A tarefa também aparece na página Verificação de Número do seu painel. O cartão dela ali pode continuar mostrando Processing (em processamento) depois de concluída, então use Status da verificação para saber o estado real.

Erros#

Os erros retornam um corpo JSON com status igual a "error" e um código de erro HTTP:

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

Como os números são verificados#

1. A tarefa entra na fila

   A API armazena cada número aceito como pending e retorna imediatamente.

2. Um número de WhatsApp conectado faz a verificação

   Os números são verificados até 10 de cada vez usando um número de WhatsApp conectado nas configurações do WhatsApp. Cada número passa a verified se estiver registrado no WhatsApp, ou a invalid se não estiver. As verificações só rodam em um número conectado que não esteja ocupado enviando mensagens, então, durante uma campanha grande, elas podem aguardar até o envio terminar.

3. Você lê os resultados

   Consulte Status da verificação periodicamente até que overall_status seja completed e então leia os números na mesma resposta ou em Resultados da verificação.

Dicas#

• Sempre inclua o código do país. Um número local de 10 dígitos sem ele passa na verificação de tamanho, mas é verificado exatamente como foi escrito, então o resultado não será do número que você queria.
• Não use o prefixo internacional 00. Apenas um 0 inicial é removido, então 00919876543210 é verificado como 0919876543210. Envie 919876543210.
• Remova os duplicados você mesmo antes de enviar, para não gastar o limite por requisição do seu plano com repetições.
• Verifique numbers_submitted para encontrar números que foram descartados por serem curtos demais ou conterem letras.
• Listas grandes: se você atingir o limite por requisição, envie várias tarefas menores e acompanhe cada campaign_id.

Novo na verificação de números? Veja o guia de Verificação de números.