WhatsApp-Nummer verbinden (API)

Starten Sie die Verbindung einer WhatsApp-Nummer mit Ihrem Arbeitsbereich direkt aus Ihrer eigenen App. Wbiztool öffnet eine neue WhatsApp-Sitzung und sendet den QR-Code an Ihre Webhook-URL. Zeigen Sie ihn dem Besitzer des Telefons, er scannt ihn mit WhatsApp, und die Nummer ist bereit zum Senden von Nachrichten.

Sie verknüpfen Ihre eigene Nummer von Hand? Folgen Sie WhatsApp-Nummer verbinden.

POST /api/v1/whatsapp-client/create/ ist ein identischer Alias: Er führt denselben Code aus und liefert dieselben Antworten. Beide Pfade funktionieren weiterhin.

So funktioniert das Verbinden#

Der API-Aufruf startet die Verbindung nur. Der QR-Code kommt später an Ihrer Webhook-URL an.

1. Connect API aufrufen

   Senden Sie die Telefonnummer und Ihre webhook_url. Die Antwort enthält eine whatsapp_client_id. Speichern Sie diese.

2. QR-Code empfangen

   Ihr Webhook erhält status=qr_generated mit dem QR-Bild in qr_image. Zeigen Sie dieses Bild der Person, der das Telefon gehört. Solange Wbiztool auf einen Scan wartet, wird der QR-Code alle paar Sekunden erneut gesendet. Zeigen Sie also immer den neuesten an. Die Person hat etwa zwei Minuten Zeit zum Scannen. Danach, oder wenn WhatsApp das Neuladen des Codes verlangt, erhalten Sie not_connected; rufen Sie die API dann erneut auf, um einen neuen Code zu erhalten.

3. Mit WhatsApp scannen

   Öffnen Sie auf dem Telefon WhatsApp → Verknüpfte Geräte → Gerät verknüpfen und scannen Sie den Code.

4. Ergebnis erhalten

   Ihr Webhook erhält status=connected, wenn die Nummer verknüpft ist, oder status=not_connected, wenn der Code nicht rechtzeitig gescannt wurde oder die Verbindung fehlgeschlagen ist. Das Ereignis connected kann einige Sekunden eintreffen, bevor Verbindungsstatus Connected zurückgibt. Beantworten Sie zuerst den Webhook und fragen Sie dann Verbindungsstatus bis zu einer Minute lang alle paar Sekunden ab. Prüfen Sie den Status nicht nur einmal aus Ihrem Webhook-Handler heraus.

Kurzes Beispiel#

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');
}

Ersetzen Sie 12345 und YOUR_API_KEY durch Ihre eigenen Werte. Wo Sie diese finden, steht unter Authentifizierung.

Request-Parameter#

Offizielle Clients verwenden#

Der Python-Client ruft /api/v1/whatsapp-client/create/ für Sie auf.

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)

Der Python-Client löst requests.exceptions.HTTPError aus, wenn die API HTTP 400 oder 403 zurückgibt. Umschließen Sie den Aufruf daher mit try/except.

Antwort#

Wenn die Verbindungsanfrage erstellt wurde, gibt die API HTTP 200 zurück:

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

"status": 1 bedeutet, dass die Anfrage erstellt wurde, nicht, dass die Nummer verbunden ist. Wenn Sie die API erneut für eine Nummer aufrufen, die früher hinzugefügt wurde, aber nicht verbunden ist, erhalten Sie dieselbe whatsapp_client_id zurück, und ein neuer Verbindungsversuch startet.

Fehler#

Ein Request, der kein POST ist, liefert ein leeres Objekt {} mit HTTP 200.

Wenn derselbe Kontoinhaber diese Nummer bereits in einem anderen Arbeitsbereich hinzugefügt hat, kann der Request mit HTTP 500 fehlschlagen. Verbinden Sie die Nummer über die WhatsApp-Einstellungen im gewünschten Arbeitsbereich oder kontaktieren Sie den Support.

Webhook-Ereignisse#

Wbiztool sendet bei jedem Schritt einen POST an Ihre webhook_url. Der Body ist formularkodiert (application/x-www-form-urlencoded), nicht JSON.

QR-Code bereit (wird während des Wartens auf einen Scan alle paar Sekunden erneut gesendet, oft mit derselben URL):

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

Nummer verbunden (kann für dieselbe Verbindung mehr als einmal gesendet werden):

status=connected&whatsapp_client_id=678

Verbindung fehlgeschlagen, zum Beispiel weil der QR-Code nicht rechtzeitig gescannt wurde:

status=not_connected&whatsapp_client_id=678

Ihre URL muss öffentlich erreichbar sein und sollte innerhalb weniger Sekunden antworten. Wbiztool wartet ohne Timeout auf Ihre Antwort. Ist Ihr Server nicht erreichbar, kann der Verbindungsversuch abbrechen, bevor die Nummer als verbunden gespeichert wird. Jeder HTTP-Statuscode wird akzeptiert. Fehlgeschlagene Zustellungen werden nicht wiederholt, und es wird nichts gesendet, wenn die Nummer später getrennt wird. Um eine Nummer nach dem Verbinden weiter zu überwachen, fragen Sie regelmäßig Verbindungsstatus ab.

Polling statt Webhooks#

Auch wenn Ihr Server keine Webhooks empfangen kann, benötigen Sie den Webhook, um den QR-Code zu erhalten. Für das Ergebnis müssen Sie sich aber nicht darauf verlassen. Rufen Sie nach dem Scannen des QR-Codes alle paar Sekunden Verbindungsstatus mit der whatsapp_client_id auf, bis Connected zurückkommt. Konten auflisten zeigt dasselbe für alle Ihre Nummern.

Tipps#

• Doppelte Ereignisse verarbeiten: connected kann zweimal ankommen. Sorgen Sie dafür, dass Ihr Handler gefahrlos mehrfach ausgeführt werden kann.
• Den neuesten QR-Code anzeigen: Ersetzen Sie das Bild jedes Mal, wenn ein neues qr_generated-Ereignis eintrifft, und hängen Sie an eine https-URL einen Cache-Busting-Query-Parameter an. Ältere Codes funktionieren nicht mehr.
• Innerhalb von etwa zwei Minuten scannen: Danach erhalten Sie not_connected. Rufen Sie die API für einen neuen Code erneut auf.
• Nach 10 Minuten kein QR-Code? Die Anfrage ist abgelaufen. Rufen Sie die API erneut auf.
• Das Verbinden über das Dashboard ist einfacher, wenn Sie Ihre eigene Nummer verknüpfen. Verwenden Sie die WhatsApp-Einstellungen und scannen Sie den Code dort.