Números

Um número é um número de WhatsApp ou uma conta do Telegram conectada ao seu espaço de trabalho. O id dele é o from com que você envia mensagens. Com a API v2, você lista os números, vê se cada um está conectado e conecta um número de WhatsApp a partir do seu próprio app, por código QR ou código de login.

Uma chave limitada a alguns números vê e reconecta só esses números e não pode adicionar um número.

Listar números#

Todos os números do espaço de trabalho, dos mais antigos para os mais recentes, em uma única lista data (sem 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 é sempre null na lista. Para acompanhar uma conexão, obtenha o número.

Obter um número#

Um número. Enquanto ele está se conectando, connect traz o código QR para escanear ou o código de login para digitar.

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"
  }
}

Um número que não existe, ou que a chave não pode usar, responde 404 number_not_found.

O objeto Number#

connect tem:

Mensagens enviadas com um número disconnected como from continuam sendo aceitas: elas esperam e saem quando ele for conectado de novo. Os eventos de webhook para números virão depois; até lá, consulte GET /numbers periodicamente para perceber um número que foi desconectado.

Conectar um número de WhatsApp#

Pede a um servidor do WbizTool que abra o WhatsApp para um número, para que você o vincule a partir do seu próprio app ou site, como faria em Números do WhatsApp. A resposta é 202 com o Number, no status connecting. Depois, consulte-o periodicamente até ele ficar connected.

Exige um plano que inclua a API de código QR; caso contrário, responde 403 plan_required. As contas do Telegram são conectadas pelo painel, não aqui.

# 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'];

O fluxo de conexão#

1. Peça a conexão

   POST /numbers com login_method (e phone para um código de login). Guarde o id da resposta. Envie uma Idempotency-Key para que uma nova tentativa não peça duas vezes.

2. Consulte o número a cada poucos segundos

   GET /numbers/{id} a cada 2 a 5 segundos enquanto status for connecting. O código QR ou o código de login aparece em connect em instantes; até lá, os campos dele são null.

3. Mostre o código QR ou o código de login

   QR: mostre a imagem de connect.qr_code_url; no celular, abra o WhatsApp → Dispositivos conectados → Conectar dispositivo e escaneie. Cada link funciona por 10 minutos e um novo chega a cada consulta, então mostre sempre o mais recente. Código de login: no celular, abra o WhatsApp → Dispositivos conectados → Conectar dispositivo → Conectar com número de telefone e digite o connect.pairing_code de 8 caracteres antes de connect.pairing_code_expires_at (cerca de 3 minutos).

4. Espere ficar conectado

   Depois do escaneamento ou do código, connect.linking fica true enquanto o WhatsApp termina a vinculação. Então status passa a connected e phone mostra o número. Pare de consultar.

Se nada acontecer em 10 minutos, a tentativa termina e status volta a disconnected. Peça de novo com POST /numbers e o number_id dele.

Enquanto um número está sendo conectado, outra requisição para ele responde 409 connect_in_progress com o number_id: continue consultando esse número em vez disso.

Erros ao conectar#

Relacionados#

• Conecte seu número de WhatsApp no painel
• Conecte uma conta do Telegram
• Mensagens: envie de um número com from
• Erros