Conectar un número de WhatsApp (API)

Inicia la conexión de un número de WhatsApp a tu espacio de trabajo desde tu propia app. WbizTool abre una nueva sesión de WhatsApp y envía un código QR, o con login_method=phone un código de 8 caracteres, a la URL de tu webhook. Muéstraselo al propietario del teléfono, que escanea el código QR o escribe el código en WhatsApp, y el número queda listo para enviar mensajes. Con un código QR no necesitas conocer el número de antemano: WbizTool lo lee de WhatsApp después del escaneo y lo envía a tu webhook.

¿Vas a vincular tu propio número a mano? Sigue Conecta tu número de WhatsApp.

POST /api/v1/whatsapp-client/create/ es un alias idéntico: ejecuta el mismo código y devuelve las mismas respuestas. Las dos rutas siguen funcionando.

Cómo funciona la conexión#

La llamada a la API solo inicia la conexión. El código QR o el código de teléfono llega más tarde, a la URL de tu webhook.

1. Llama a la API de conexión

   Envía tu webhook_url, más whatsapp_number con login_method=phone. Para reconectar un número que añadiste antes, envía también su whatsapp_client_id. La respuesta te da un whatsapp_client_id. Guárdalo.

2. Recibe el código QR o el código de teléfono

   Con el valor predeterminado login_method=qr, tu webhook recibe status=qr_generated con la imagen del QR en qr_image. El código QR se vuelve a enviar cada varios segundos mientras WbizTool espera el escaneo, así que muestra siempre el más reciente. La persona tiene unos dos minutos para escanearlo.

   Con login_method=phone, tu webhook recibe status=pairing_code con un código de 8 caracteres en pairing_code, como K5EWPGY5. Se envía una sola vez y es válido durante unos tres minutos.

   Muestra la imagen o el código a la persona propietaria del teléfono. Si no se usa a tiempo, o si WhatsApp pide recargar el código, recibes not_connected; vuelve a llamar a la API para obtener uno nuevo.

3. Vincula el teléfono

   En el teléfono, abre WhatsApp → Dispositivos vinculados → Vincular un dispositivo. Escanea el código QR, o toca Vincular con el número de teléfono y escribe el código de 8 caracteres.

4. Obtén el resultado

   Tu webhook recibe status=connected con el número vinculado en whatsapp_number cuando el número queda vinculado, o status=not_connected si el código no se escaneó a tiempo o la conexión falló. El evento connected puede llegar unos segundos antes de que Estado de conexión devuelva Connected. Responde primero al webhook y luego consulta Estado de conexión cada pocos segundos durante hasta un minuto. No lo compruebes una sola vez desde dentro del manejador de tu webhook.

Ejemplo rápido#

curl -X POST https://wbiztool.com/api/v1/whatsapp/connect/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET"
  }'

import requests

response = requests.post(
    "https://wbiztool.com/api/v1/whatsapp/connect/",
    json={
        "client_id": 12345,
        "api_key": "YOUR_API_KEY",
        "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
    },
    timeout=30,
)
result = response.json()  # read the body even when the HTTP code is 400 or 403

if result.get("status") == 1:
    print("Waiting for QR code, whatsapp_client_id", result["whatsapp_client_id"])
else:
    print("Failed:", result.get("message"))

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/whatsapp/connect/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: 12345,
    api_key: "YOUR_API_KEY",
    webhook_url: "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
  }),
});
const result = await response.json(); // read the body even when the HTTP code is 400 or 403

if (result.status === 1) {
  console.log("Waiting for QR code, whatsapp_client_id", result.whatsapp_client_id);
} else {
  console.error("Failed:", result.message);
}

<?php
$payload = [
    'client_id'       => 12345,
    'api_key'         => 'YOUR_API_KEY',
    'webhook_url'     => 'https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET',
];

$ch = curl_init('https://wbiztool.com/api/v1/whatsapp/connect/');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($result['status'] ?? 0) === 1) {
    echo 'Waiting for QR code, whatsapp_client_id ' . $result['whatsapp_client_id'];
} else {
    echo 'Failed: ' . ($result['message'] ?? 'no response');
}

Sustituye 12345 y YOUR_API_KEY por tus propios valores. Consulta Autenticación para saber dónde encontrarlos. Para obtener un código de teléfono en su lugar, añade "login_method": "phone" y "whatsapp_number": "919876543210".

Parámetros de la solicitud#

Usar los clientes oficiales#

El cliente de Python llama a /api/v1/whatsapp-client/create/ por ti. Pide whatsapp_number; con un código QR, el valor se ignora.

from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)

result = client.create_whatsapp_client(
    whatsapp_number="919876543210",
    webhook_url="https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
)
print(result)

El cliente de Python lanza requests.exceptions.HTTPError cuando la API devuelve HTTP 400 o 403, así que envuelve la llamada en un try/except.

Respuesta#

Cuando se crea la solicitud de conexión, la API devuelve HTTP 200:

{
  "message": "Whatsapp Client Created",
  "whatsapp_client_id": 678,
  "login_method": "qr",
  "status": 1
}

"status": 1 significa que la solicitud se creó, no que el número esté conectado. Volver a llamar a la API no acumula números:

• Con un código QR y sin whatsapp_client_id, recibes el mismo whatsapp_client_id hasta que se escanee uno de sus códigos QR.
• Con login_method=phone, un número que ya se había añadido pero no está conectado recibe su whatsapp_client_id existente.
• Con whatsapp_client_id, ese número se reconecta.

Hasta que se escanea su primer código QR, el número aún no tiene número de teléfono: Listar números conectados y Estado de conexión devuelven un número vacío para él.

Errores#

Una solicitud que no sea POST devuelve un objeto vacío {} con HTTP 200.

Eventos del webhook#

WbizTool envía un POST a tu webhook_url en cada paso. El cuerpo va codificado como formulario (application/x-www-form-urlencoded), no como JSON.

Código QR listo (se vuelve a enviar cada varios segundos mientras se espera el escaneo, a menudo con la misma URL):

status=qr_generated&whatsapp_client_id=678&qr_image=...

Código de teléfono listo (con login_method=phone, se envía una sola vez):

status=pairing_code&whatsapp_client_id=678&pairing_code=K5EWPGY5

Número conectado, con el número que tiene la sesión iniciada, tal como lo indica WhatsApp:

status=connected&whatsapp_client_id=678&whatsapp_number=919876543210

Conexión fallida, por ejemplo porque el código QR no se escaneó o el código de teléfono no se introdujo a tiempo:

status=not_connected&whatsapp_client_id=678

Tu URL debe ser accesible públicamente y debería responder en pocos segundos. WbizTool espera tu respuesta hasta 10 segundos; si tu servidor es lento o no se puede acceder a él, ese evento se pierde, pero el intento de conexión continúa. Se acepta cualquier código de estado HTTP. Los envíos fallidos no se reintentan, y no se envía nada si el número se desconecta más adelante. Para hacer seguimiento de un número después de conectarlo, consulta periódicamente Estado de conexión.

Consultas periódicas en lugar de webhooks#

Si tu servidor no puede recibir webhooks, sigues necesitando el webhook para obtener el código QR, pero no tienes que depender de él para el resultado. Después de escanear el código QR, llama a Estado de conexión con el whatsapp_client_id cada pocos segundos hasta que devuelva Connected. Listar cuentas muestra lo mismo para todos tus números.

Consejos#

• Gestiona los eventos duplicados: haz que tu código pueda ejecutarse más de una vez sin problemas, por si un evento llega dos veces.
• Muestra el código QR más reciente: sustituye la imagen cada vez que llegue un nuevo evento qr_generated, añadiendo un parámetro para evitar la caché a una URL https. Los códigos anteriores dejan de funcionar.
• Escanea en unos dos minutos: después recibes not_connected. Vuelve a llamar a la API para obtener un código nuevo.
• Comprueba el número tras un escaneo QR: el whatsapp_number del evento connected es el número que realmente se vinculó, que puede ser distinto del que esperabas.
• Introduce el código de teléfono en unos tres minutos: cada intento da un solo código. Si caduca, recibes not_connected; vuelve a llamar a la API.
• ¿No llega ningún código QR ni código de teléfono tras 10 minutos? La solicitud caducó. Vuelve a llamar a la API.
• Conectar desde el panel es más sencillo cuando vinculas tu propio número. Usa la configuración de WhatsApp y escanea allí el código.