Connecter un numéro WhatsApp (API)

Lancez la connexion d'un numéro WhatsApp à votre espace de travail depuis votre propre application. WbizTool ouvre une nouvelle session WhatsApp et envoie un QR code, ou avec login_method=phone un code de 8 caractères, à l'URL de votre webhook. Montrez-le au propriétaire du téléphone, qui scanne le QR code ou saisit le code dans WhatsApp, et le numéro est prêt à envoyer des messages. Avec un QR code, vous n'avez pas besoin de connaître le numéro à l'avance : WbizTool le lit dans WhatsApp après le scan et l'envoie à votre webhook.

Vous associez votre propre numéro manuellement ? Suivez Connecter votre numéro WhatsApp.

POST /api/v1/whatsapp-client/create/ est un alias identique : il exécute le même code et renvoie les mêmes réponses. Les deux chemins continuent de fonctionner.

Fonctionnement de la connexion#

L'appel API ne fait que lancer la connexion. Le QR code ou le code téléphone arrive plus tard, à l'URL de votre webhook.

1. Appelez l'API de connexion

   Envoyez votre webhook_url, ainsi que whatsapp_number avec login_method=phone. Pour reconnecter un numéro ajouté auparavant, envoyez aussi son whatsapp_client_id. La réponse vous fournit un whatsapp_client_id. Enregistrez-le.

2. Recevez le QR code ou le code téléphone

   Avec la valeur par défaut login_method=qr, votre webhook reçoit status=qr_generated avec l'image du QR code dans qr_image. Le QR code est renvoyé toutes les quelques secondes tant que WbizTool attend un scan : affichez donc toujours le plus récent. La personne dispose d'environ deux minutes pour scanner.

   Avec login_method=phone, votre webhook reçoit status=pairing_code avec un code de 8 caractères dans pairing_code, par exemple K5EWPGY5. Il est envoyé une seule fois et reste valable environ trois minutes.

   Montrez l'image ou le code à la personne à qui appartient le téléphone. S'il n'est pas utilisé à temps, ou si WhatsApp demande de recharger le code, vous recevez not_connected ; appelez de nouveau l'API pour en obtenir un nouveau.

3. Associez le téléphone

   Sur le téléphone, ouvrez WhatsApp → Appareils connectés → Connecter un appareil. Scannez le QR code, ou appuyez sur Associer avec le numéro de téléphone et saisissez le code de 8 caractères.

4. Obtenez le résultat

   Votre webhook reçoit status=connected avec le numéro associé dans whatsapp_number lorsque le numéro est associé, ou status=not_connected si le code n'a pas été scanné à temps ou si la connexion a échoué. L'événement connected peut arriver quelques secondes avant que Statut de connexion ne renvoie Connected. Répondez d'abord au webhook, puis interrogez Statut de connexion toutes les quelques secondes pendant une minute au maximum. Ne faites pas une seule vérification depuis votre gestionnaire de webhook.

Exemple rapide#

curl -X POST https://wbiztool.com/api/v1/whatsapp/connect/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "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",
        "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",
    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',
    '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');
}

Remplacez 12345 et YOUR_API_KEY par vos propres valeurs. Consultez Authentification pour savoir où les trouver. Pour obtenir plutôt un code téléphone, ajoutez "login_method": "phone" et "whatsapp_number": "919876543210".

Paramètres de la requête#

Utiliser les clients officiels#

Le client Python appelle /api/v1/whatsapp-client/create/ pour vous. Il demande whatsapp_number ; avec un QR code, la valeur est ignorée.

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)

Le client Python lève requests.exceptions.HTTPError lorsque l'API renvoie le code HTTP 400 ou 403 : encapsulez donc l'appel dans un bloc try/except.

Réponse#

Lorsque la demande de connexion est créée, l'API renvoie le code HTTP 200 :

{
  "message": "Whatsapp Client Created",
  "whatsapp_client_id": 678,
  "login_method": "qr",
  "status": 1
}

"status": 1 signifie que la demande a été créée, pas que le numéro est connecté. Appeler de nouveau l'API n'accumule pas les numéros :

• Avec un QR code et sans whatsapp_client_id, vous récupérez le même whatsapp_client_id jusqu'à ce que l'un de ses QR codes soit scanné.
• Avec login_method=phone, un numéro déjà ajouté mais non connecté récupère son whatsapp_client_id existant.
• Avec whatsapp_client_id, ce numéro est reconnecté.

Tant que son premier QR code n'a pas été scanné, le numéro n'a pas encore de numéro de téléphone : Lister les numéros connectés et Statut de connexion renvoient un numéro vide pour lui.

Erreurs#

Une requête qui n'est pas un POST renvoie un objet vide {} avec le code HTTP 200.

Événements webhook#

WbizTool envoie un POST à votre webhook_url à chaque étape. Le corps est encodé comme un formulaire (application/x-www-form-urlencoded), et non en JSON.

QR code prêt (renvoyé toutes les quelques secondes pendant l'attente d'un scan, souvent avec la même image) :

status=qr_generated&whatsapp_client_id=678&qr_image=...

Code téléphone prêt (avec login_method=phone, envoyé une seule fois) :

status=pairing_code&whatsapp_client_id=678&pairing_code=K5EWPGY5

Numéro connecté, avec le numéro connecté tel que WhatsApp l'indique :

status=connected&whatsapp_client_id=678&whatsapp_number=919876543210

Échec de la connexion, par exemple parce que le QR code n'a pas été scanné ou le code téléphone n'a pas été saisi à temps :

status=not_connected&whatsapp_client_id=678

Votre URL doit être accessible publiquement et devrait répondre en quelques secondes. WbizTool attend votre réponse jusqu'à 10 secondes ; si votre serveur est lent ou injoignable, cet événement est perdu, mais la tentative de connexion se poursuit. Tous les codes de statut HTTP sont acceptés. Les envois en échec ne sont pas retentés, et rien n'est envoyé si le numéro se déconnecte par la suite. Pour suivre un numéro après sa connexion, interrogez régulièrement Statut de connexion.

Interroger l'API plutôt qu'utiliser des webhooks#

Si votre serveur ne peut pas recevoir de webhooks, le webhook reste nécessaire pour obtenir le QR code, mais vous n'avez pas besoin d'en dépendre pour le résultat. Une fois le QR code scanné, appelez Statut de connexion avec le whatsapp_client_id toutes les quelques secondes jusqu'à ce qu'il renvoie Connected. Lister les comptes fournit la même information pour tous vos numéros.

Conseils#

• Gérez les événements en double : faites en sorte que votre gestionnaire puisse s'exécuter plusieurs fois sans problème, au cas où un événement serait livré deux fois.
• Affichez le QR code le plus récent : remplacez l'image à chaque nouvel événement qr_generated, en ajoutant un paramètre anti-cache à une URL https. Les codes plus anciens cessent de fonctionner.
• Scannez en deux minutes environ : passé ce délai, vous recevez not_connected. Appelez de nouveau l'API pour obtenir un nouveau code.
• Vérifiez le numéro après un scan de QR code : le whatsapp_number de l'événement connected est le numéro réellement associé, qui peut différer de celui que vous attendiez.
• Saisissez le code téléphone en trois minutes environ : chaque tentative fournit un seul code. S'il expire, vous recevez not_connected ; appelez de nouveau l'API.
• Pas de QR code ni de code téléphone au bout de 10 minutes ? La demande a expiré. Appelez de nouveau l'API.
• La connexion depuis le tableau de bord est plus simple lorsque vous associez votre propre numéro. Utilisez les paramètres WhatsApp et scannez le code depuis cette page.