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 el código QR a la URL de tu webhook. Muéstraselo al propietario del teléfono, que lo escanea desde WhatsApp, y el número queda listo para enviar mensajes.

¿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 llega más tarde, a la URL de tu webhook.

1. Llama a la API de conexión

   Envía el número de teléfono y tu webhook_url. La respuesta te da un whatsapp_client_id. Guárdalo.

2. Recibe el código QR

   Tu webhook recibe status=qr_generated con la imagen del QR en qr_image. Muestra esa imagen a la persona propietaria del teléfono. 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. Después de ese tiempo, o si WhatsApp pide recargar el código, recibes not_connected; vuelve a llamar a la API para obtener un código nuevo.

3. Escanéalo desde WhatsApp

   En el teléfono, abre WhatsApp → Dispositivos vinculados → Vincular un dispositivo y escanea el código.

4. Obtén el resultado

   Tu webhook recibe status=connected 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",
    "whatsapp_number": "919876543210",
    "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",
        "whatsapp_number": "919876543210",
        "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",
    whatsapp_number: "919876543210",
    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',
    'whatsapp_number' => '919876543210',
    '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.

Parámetros de la solicitud#

Usar los clientes oficiales#

El cliente de Python llama a /api/v1/whatsapp-client/create/ por ti.

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,
  "status": 1
}

"status": 1 significa que la solicitud se creó, no que el número esté conectado. Si vuelves a llamar a la API con un número que ya se había añadido pero no está conectado, recibes el mismo whatsapp_client_id y se inicia un nuevo intento de conexión.

Errores#

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

Si el mismo propietario de la cuenta ya añadió este número en otro espacio de trabajo, la solicitud puede fallar con HTTP 500. Conecta el número desde la configuración de WhatsApp en el espacio de trabajo que quieras, o contacta con soporte.

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=...

Número conectado (puede enviarse más de una vez para la misma conexión):

status=connected&whatsapp_client_id=678

Conexión fallida, por ejemplo porque el código QR no se escaneó 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 sin límite de tiempo. Si no se puede acceder a tu servidor, el intento de conexión puede detenerse antes de que el número se guarde como conectado. 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: connected puede llegar dos veces. Haz que tu código pueda ejecutarse más de una vez sin problemas.
• 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.
• ¿No llega ningún código QR 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.