Números

Un número es un número de WhatsApp o una cuenta de Telegram conectada a tu espacio de trabajo. Su id es el from con el que envías mensajes. Con la API v2 los listas, ves si cada uno está conectado y conectas un número de WhatsApp desde tu propia app, con código QR o código de vinculación.

Una clave limitada a algunos números solo ve y vuelve a conectar esos números, y no puede añadir un número.

Listar números#

Todos los números del espacio de trabajo, primero los más antiguos, en una sola lista data (sin páginas).

curl https://wbiztool.com/api/v2/numbers \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

import os
import requests

response = requests.get(
    "https://wbiztool.com/api/v2/numbers",
    headers={"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"},
    timeout=30,
)
for number in response.json()["data"]:
    print(number["id"], number["phone"], number["label"], number["status"])

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/numbers", {
  headers: { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}` },
});
const { data } = await response.json();
for (const number of data) console.log(number.id, number.phone, number.label, number.status);

<?php
$ch = curl_init('https://wbiztool.com/api/v2/numbers');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
]);
$numbers = json_decode(curl_exec($ch), true)['data'];
curl_close($ch);
foreach ($numbers as $number) {
    echo $number['id'] . ' ' . $number['phone'] . ' ' . $number['status'] . "\n";
}

{
  "data": [
    {
      "id": 101,
      "phone": "919800000000",
      "label": "Shop",
      "platform": "whatsapp",
      "status": "connected",
      "login_method": "qr",
      "connect": null
    },
    {
      "id": 102,
      "phone": null,
      "label": "",
      "platform": "whatsapp",
      "status": "disconnected",
      "login_method": "qr",
      "connect": null
    }
  ]
}

connect siempre es null en la lista. Para seguir una conexión, obtén el número.

Obtener un número#

Un número. Mientras se está conectando, connect contiene el código QR que hay que escanear o el código de vinculación que hay que escribir.

curl https://wbiztool.com/api/v2/numbers/102 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

{
  "id": 102,
  "phone": null,
  "label": "",
  "platform": "whatsapp",
  "status": "connecting",
  "login_method": "qr",
  "connect": {
    "qr_code_url": "https://…/qr_codes/…png?X-Amz-Signature=…",
    "pairing_code": null,
    "pairing_code_expires_at": null,
    "linking": false,
    "requested_at": "2026-10-18T11:02:15.402Z"
  }
}

Un número que no existe, o que la clave no puede usar, responde 404 number_not_found.

El objeto Number#

connect contiene:

Los mensajes enviados con un número disconnected como from se siguen aceptando: esperan y salen cuando el número vuelve a estar conectado. Los eventos de webhook para números llegarán más adelante; hasta entonces, consulta GET /numbers periódicamente para detectar un número que se desconectó.

Conectar un número de WhatsApp#

Pide a un servidor de WbizTool que abra WhatsApp para un número, para que puedas vincularlo desde tu propia app o sitio web, igual que en Números de WhatsApp. La respuesta es 202 con el Number, en estado connecting. Después, consúltalo periódicamente hasta que esté connected.

Necesita un plan que incluya la API de código QR; si no, responde 403 plan_required. Las cuentas de Telegram se conectan en el panel, no aquí.

# By QR code
curl -X POST https://wbiztool.com/api/v2/numbers \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"login_method": "qr"}'

# By pairing code, reconnecting number 101
curl -X POST https://wbiztool.com/api/v2/numbers \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"login_method": "phone_code", "phone": "+919876543210", "number_id": 101}'

import os
import time
import requests

API = "https://wbiztool.com/api/v2"
headers = {"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"}

number = requests.post(f"{API}/numbers", headers=headers,
                       json={"login_method": "phone_code", "phone": "+919876543210"}, timeout=30).json()

shown = None
while number["status"] == "connecting":
    time.sleep(3)
    number = requests.get(f"{API}/numbers/{number['id']}", headers=headers, timeout=30).json()
    code = (number["connect"] or {}).get("pairing_code")
    if code and code != shown:
        print("On the phone: WhatsApp → Linked devices → Link with phone number, then type", code)
        shown = code

print("Number", number["id"], "is", number["status"])

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const API = "https://wbiztool.com/api/v2";
const headers = { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}`, "Content-Type": "application/json" };

let number = await (await fetch(`${API}/numbers`, {
  method: "POST", headers, body: JSON.stringify({ login_method: "qr" }),
})).json();

let shown = null;
while (number.status === "connecting") {
  await new Promise((r) => setTimeout(r, 3000));
  number = await (await fetch(`${API}/numbers/${number.id}`, { headers })).json();
  const qr = number.connect?.qr_code_url;
  if (qr && qr !== shown) {
    console.log("Show this QR code to scan:", qr); // e.g. in an <img> on your page
    shown = qr;
  }
}
console.log(`Number ${number.id} is ${number.status}`);

<?php
$ch = curl_init('https://wbiztool.com/api/v2/numbers');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['login_method' => 'qr']),
    CURLOPT_RETURNTRANSFER => true,
]);
$number = json_decode(curl_exec($ch), true);
curl_close($ch);
// Save $number['id'], then poll GET /api/v2/numbers/{id} every few seconds (see The connect flow).
echo $number['id'] . ' ' . $number['status'];

El flujo de conexión#

1. Pide la conexión

   POST /numbers con login_method (y phone para un código de vinculación). Guarda el id de la respuesta. Envía una Idempotency-Key para que un reintento no lo pida dos veces.

2. Consulta el número cada pocos segundos

   GET /numbers/{id} cada 2 a 5 segundos mientras status sea connecting. El código QR o el código de vinculación aparece en connect en unos instantes; hasta entonces sus campos son null.

3. Muestra el código QR o el código de vinculación

   QR: muestra la imagen de connect.qr_code_url; en el teléfono, abre WhatsApp → Dispositivos vinculados → Vincular un dispositivo y escanéala. Cada enlace funciona durante 10 minutos y llega uno nuevo en cada consulta, así que muestra siempre el más reciente. Código de vinculación: en el teléfono, abre WhatsApp → Dispositivos vinculados → Vincular un dispositivo → Vincular con el número de teléfono y escribe el connect.pairing_code de 8 caracteres antes de connect.pairing_code_expires_at (unos 3 minutos).

4. Espera a que esté conectado

   Después del escaneo o del código, connect.linking es true mientras WhatsApp termina de vincular. Luego status pasa a connected y phone muestra el número. Deja de consultar.

Si no pasa nada en 10 minutos, el intento termina y status vuelve a disconnected. Vuelve a pedirlo con POST /numbers y su number_id.

Mientras un número se está conectando, otra solicitud para él responde 409 connect_in_progress con su number_id: sigue consultando ese en su lugar.

Errores al conectar#

Relacionado#

• Conecta tu número de WhatsApp en el panel
• Conecta una cuenta de Telegram
• Mensajes: envía desde un número con from
• Errores