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 einen QR-Code oder, mit login_method=phone, einen 8-stelligen Code an Ihre Webhook-URL. Zeigen Sie ihn dem Besitzer des Telefons, er scannt den QR-Code oder gibt den Code in WhatsApp ein, und die Nummer ist bereit zum Senden von Nachrichten. Bei einem QR-Code müssen Sie die Nummer nicht im Voraus kennen: WbizTool liest sie nach dem Scan aus WhatsApp aus und sendet sie an Ihren Webhook.

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 oder Telefoncode kommt später an Ihrer Webhook-URL an.

1. Connect API aufrufen

   Senden Sie Ihre webhook_url und bei login_method=phone zusätzlich whatsapp_number. Um eine früher hinzugefügte Nummer erneut zu verbinden, senden Sie außerdem ihre whatsapp_client_id. Die Antwort enthält eine whatsapp_client_id. Speichern Sie diese.

2. QR-Code oder Telefoncode empfangen

   Mit dem Standardwert login_method=qr erhält Ihr Webhook status=qr_generated mit dem QR-Bild in qr_image. 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.

   Mit login_method=phone erhält Ihr Webhook status=pairing_code mit einem 8-stelligen Code in pairing_code, zum Beispiel K5EWPGY5. Er wird einmal gesendet und ist etwa drei Minuten gültig.

   Zeigen Sie das Bild oder den Code der Person, der das Telefon gehört. Wird er nicht rechtzeitig verwendet oder verlangt WhatsApp das Neuladen des Codes, erhalten Sie not_connected; rufen Sie die API dann erneut auf, um einen neuen zu erhalten.

3. Telefon verknüpfen

   Öffnen Sie auf dem Telefon WhatsApp → Verknüpfte Geräte → Gerät verknüpfen. Scannen Sie den QR-Code oder tippen Sie auf Stattdessen mit Telefonnummer verknüpfen und geben Sie den 8-stelligen Code ein.

4. Ergebnis erhalten

   Ihr Webhook erhält status=connected mit der verknüpften Nummer in whatsapp_number, 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",
    "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');
}

Ersetzen Sie 12345 und YOUR_API_KEY durch Ihre eigenen Werte. Wo Sie diese finden, steht unter Authentifizierung. Um stattdessen einen Telefoncode zu erhalten, fügen Sie "login_method": "phone" und "whatsapp_number": "919876543210" hinzu.

Request-Parameter#

Offizielle Clients verwenden#

Der Python-Client ruft /api/v1/whatsapp-client/create/ für Sie auf. Er verlangt whatsapp_number; bei einem QR-Code wird der Wert ignoriert.

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

"status": 1 bedeutet, dass die Anfrage erstellt wurde, nicht, dass die Nummer verbunden ist. Ein erneuter Aufruf der API häuft keine Nummern an:

• Bei einem QR-Code ohne whatsapp_client_id erhalten Sie dieselbe whatsapp_client_id zurück, bis einer ihrer QR-Codes gescannt wird.
• Mit login_method=phone erhält eine Nummer, die früher hinzugefügt wurde, aber nicht verbunden ist, ihre bestehende whatsapp_client_id zurück.
• Mit whatsapp_client_id wird diese Nummer erneut verbunden.

Bis ihr erster QR-Code gescannt wird, hat die Nummer noch keine Telefonnummer: Verbundene Nummern auflisten und Verbindungsstatus geben für sie eine leere Nummer zurück.

Fehler#

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

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 demselben Bild):

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

Telefoncode bereit (mit login_method=phone, wird einmal gesendet):

status=pairing_code&whatsapp_client_id=678&pairing_code=K5EWPGY5

Nummer verbunden, mit der angemeldeten Nummer, wie WhatsApp sie meldet:

status=connected&whatsapp_client_id=678&whatsapp_number=919876543210

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

status=not_connected&whatsapp_client_id=678

Ihre URL muss öffentlich erreichbar sein und sollte innerhalb weniger Sekunden antworten. WbizTool wartet bis zu 10 Sekunden auf Ihre Antwort; ist Ihr Server zu langsam oder nicht erreichbar, geht dieses Ereignis verloren, der Verbindungsversuch läuft aber weiter. 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: Sorgen Sie dafür, dass Ihr Handler gefahrlos mehrfach ausgeführt werden kann, falls ein Ereignis zweimal zugestellt wird.
• 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.
• Nummer nach einem QR-Scan prüfen: Die whatsapp_number im connected-Ereignis ist die tatsächlich verknüpfte Nummer, die von der erwarteten abweichen kann.
• Telefoncode innerhalb von etwa drei Minuten eingeben: Jeder Versuch liefert einen Code. Läuft er ab, erhalten Sie not_connected; rufen Sie die API erneut auf.
• Nach 10 Minuten kein QR-Code und kein Telefoncode? 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.