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 le QR code à l'URL de votre webhook. Montrez-le au propriétaire du téléphone, qui le scanne depuis WhatsApp, et le numéro est prêt à envoyer des messages.

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 arrive plus tard, à l'URL de votre webhook.

1. Appelez l'API de connexion

   Envoyez le numéro de téléphone et votre webhook_url. La réponse vous fournit un whatsapp_client_id. Enregistrez-le.

2. Recevez le QR code

   Votre webhook reçoit status=qr_generated avec l'image du QR code dans qr_image. Montrez cette image à la personne à qui appartient le téléphone. 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. Passé ce délai, ou si WhatsApp demande de recharger le code, vous recevez not_connected ; appelez de nouveau l'API pour obtenir un nouveau code.

3. Scannez-le depuis WhatsApp

   Sur le téléphone, ouvrez WhatsApp → Appareils connectés → Connecter un appareil et scannez le code.

4. Obtenez le résultat

   Votre webhook reçoit status=connected 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",
    "whatsapp_number": "919876543210",
    "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",
        "whatsapp_number": "919876543210",
        "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",
    whatsapp_number: "919876543210",
    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',
    'whatsapp_number' => '919876543210',
    '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.

Paramètres de la requête#

Utiliser les clients officiels#

Le client Python appelle /api/v1/whatsapp-client/create/ pour vous.

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,
  "status": 1
}

"status": 1 signifie que la demande a été créée, pas que le numéro est connecté. Si vous appelez de nouveau l'API pour un numéro déjà ajouté mais non connecté, vous récupérez le même whatsapp_client_id et une nouvelle tentative de connexion démarre.

Erreurs#

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

Si le même propriétaire de compte a déjà ajouté ce numéro dans un autre espace de travail, la requête peut échouer avec le code HTTP 500. Connectez le numéro depuis les paramètres WhatsApp dans l'espace de travail souhaité, ou contactez le support.

É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 URL) :

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

Numéro connecté (peut être envoyé plusieurs fois pour la même connexion) :

status=connected&whatsapp_client_id=678

Échec de la connexion, par exemple parce que le QR code n'a pas été scanné à 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 sans délai d'expiration. Si votre serveur est injoignable, la tentative de connexion peut s'arrêter avant que le numéro soit enregistré comme connecté. 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 : connected peut arriver deux fois. Faites en sorte que votre gestionnaire puisse s'exécuter plusieurs fois sans problème.
• 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.
• Pas de QR code 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.