Numeri

Un numero è un numero WhatsApp o un account Telegram collegato al tuo spazio di lavoro. Il suo id è il from con cui invii i messaggi. Con l'API v2 puoi elencarli, vedere se ciascuno è collegato e collegare un numero WhatsApp dalla tua app, con codice QR o codice di abbinamento.

Una chiave limitata ad alcuni numeri vede e ricollega solo quelli, e non può aggiungere un numero.

Elencare i numeri#

Tutti i numeri dello spazio di lavoro, dal più vecchio, in un'unica lista data (senza pagine).

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

Nella lista connect è sempre null. Per seguire un collegamento, ottieni il numero.

Ottenere un numero#

Un singolo numero. Mentre è in collegamento, connect contiene il codice QR da scansionare o il codice di abbinamento da digitare.

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 numero che non esiste, o che la chiave non può usare, risponde 404 number_not_found.

L'oggetto Number#

connect contiene:

I messaggi inviati con un numero disconnected come from vengono comunque accettati: restano in attesa e partono quando il numero è di nuovo collegato. Gli eventi webhook per i numeri arriveranno più avanti; fino ad allora, interroga GET /numbers per accorgerti di un numero disconnesso.

Collegare un numero WhatsApp#

Chiede a un server WbizTool di aprire WhatsApp per un numero, così puoi collegarlo dalla tua app o dal tuo sito, come faresti nella pagina Numeri WhatsApp. La risposta è 202 con il Number, con stato connecting. Poi interrogalo finché non è connected.

Richiede un piano che includa l'API del codice QR; altrimenti risponde 403 plan_required. Gli account Telegram si collegano nella dashboard, non qui.

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

Il flusso di collegamento#

1. Richiedi il collegamento

   POST /numbers con login_method (e phone per un codice di abbinamento). Conserva l'id della risposta. Invia un Idempotency-Key, così un nuovo tentativo non fa una seconda richiesta.

2. Interroga il numero ogni pochi secondi

   GET /numbers/{id} ogni 2-5 secondi finché status è connecting. Il codice QR o il codice di abbinamento compare in connect in pochi istanti; fino ad allora i suoi campi sono null.

3. Mostra il codice QR o il codice di abbinamento

   QR: mostra l'immagine di connect.qr_code_url; sul telefono apri WhatsApp → Dispositivi collegati → Collega un dispositivo e scansionala. Ogni link funziona per 10 minuti e a ogni interrogazione ne arriva uno nuovo, quindi mostra ogni volta il più recente. Codice di abbinamento: sul telefono apri WhatsApp → Dispositivi collegati → Collega un dispositivo → Collega con il numero di telefono e digita il connect.pairing_code di 8 caratteri prima di connect.pairing_code_expires_at (circa 3 minuti).

4. Attendi lo stato connected

   Dopo la scansione o il codice, connect.linking è true mentre WhatsApp completa il collegamento. Poi status diventa connected e phone mostra il numero. Smetti di interrogare.

Se per 10 minuti non succede nulla, il tentativo termina e status torna a disconnected. Richiedilo di nuovo con POST /numbers e il suo number_id.

Mentre un numero è in collegamento, un'altra richiesta per quel numero risponde 409 connect_in_progress con il suo number_id: continua invece a interrogare quello.

Errori durante il collegamento#

Pagine correlate#

• Collega il tuo numero WhatsApp nella dashboard
• Collega un account Telegram
• Messaggi: invia da un numero con from
• Errori