Numéros

Un numéro est un numéro WhatsApp ou un compte Telegram connecté à votre espace de travail. Son id est le from avec lequel vous envoyez des messages. Avec l'API v2, vous les listez, vous voyez si chacun est connecté, et vous connectez un numéro WhatsApp depuis votre propre application, par code QR ou code d'association.

Une clé limitée à certains numéros ne voit et ne reconnecte que ceux-là, et ne peut pas ajouter de numéro.

Lister les numéros#

Tous les numéros de l'espace de travail, les plus anciens d'abord, dans une seule liste data (sans pages).

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 vaut toujours null dans la liste. Pour suivre une connexion, obtenez le numéro.

Obtenir un numéro#

Un numéro. Pendant sa connexion, connect contient le code QR à scanner ou le code d'association à saisir.

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 numéro qui n'existe pas, ou que la clé ne peut pas utiliser, répond 404 number_not_found.

L'objet Numéro#

connect contient :

Les messages envoyés avec un numéro disconnected comme from sont tout de même acceptés : ils attendent et partent quand il est de nouveau connecté. Les événements webhook pour les numéros viendront plus tard ; d'ici là, interrogez GET /numbers régulièrement pour repérer un numéro déconnecté.

Connecter un numéro WhatsApp#

Demande à un serveur WbizTool d'ouvrir WhatsApp pour un numéro, afin que vous puissiez l'associer depuis votre propre application ou site web, comme vous le feriez sur Numéros WhatsApp. La réponse est 202 avec le Numéro, au statut connecting. Ensuite, interrogez-le jusqu'à ce qu'il soit connected.

Il faut un forfait qui inclut l'API du code QR ; sinon, la réponse est 403 plan_required. Les comptes Telegram se connectent dans le tableau de bord, pas ici.

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

Le déroulement de la connexion#

1. Demandez la connexion

   POST /numbers avec login_method (et phone pour un code d'association). Gardez l'id de la réponse. Envoyez une Idempotency-Key pour qu'une nouvelle tentative ne fasse pas la demande deux fois.

2. Interrogez le numéro toutes les quelques secondes

   GET /numbers/{id} toutes les 2 à 5 secondes tant que status vaut connecting. Le code QR ou le code d'association apparaît dans connect en quelques instants ; d'ici là, ses champs valent null.

3. Affichez le code QR ou le code d'association

   Code QR : affichez l'image de connect.qr_code_url ; sur le téléphone, ouvrez WhatsApp → Appareils connectés → Connecter un appareil et scannez-la. Chaque lien fonctionne 10 minutes et un nouveau arrive à chaque interrogation : affichez donc toujours le plus récent. Code d'association : sur le téléphone, ouvrez WhatsApp → Appareils connectés → Connecter un appareil → Associer avec le numéro de téléphone, et saisissez le connect.pairing_code de 8 caractères avant connect.pairing_code_expires_at (environ 3 minutes).

4. Attendez l'état connecté

   Après le scan ou la saisie du code, connect.linking vaut true pendant que WhatsApp termine l'association. Ensuite, status devient connected et phone affiche le numéro. Arrêtez d'interroger.

Si rien ne se passe pendant 10 minutes, la tentative prend fin et status revient à disconnected. Faites une nouvelle demande avec POST /numbers et son number_id.

Pendant qu'un numéro est en cours de connexion, une autre demande pour lui répond 409 connect_in_progress avec son number_id : continuez plutôt d'interroger celui-là.

Erreurs à la connexion#

Voir aussi#

• Connecter votre numéro WhatsApp dans le tableau de bord
• Connecter un compte Telegram
• Messages : envoyer depuis un numéro avec from
• Erreurs