· 4 min · TextMeFlow Team

WhatsApp per QR-Code koppeln: Pairing, Polling, Neu-Pairing

Bevor du über TextMeFlow auch nur eine Nachricht senden kannst, muss deine WhatsApp-Nummer mit deinem Konto verbunden sein. Das funktioniert wie „WhatsApp Web" oder „Verknüpfte Geräte" in der offiziellen WhatsApp-App: Du scannst einmal einen QR-Code, und die Verbindung bleibt aktiv, bis du sie ausdrücklich abmeldest oder WhatsApp eine neue Verknüpfung erzwingt. Es gibt keine zusätzliche App zu installieren und keine Rufnummernmitnahme: Deine Nummer funktioniert auf deinem Handy ganz normal weiter, während TextMeFlow über dieselbe Sitzung sendet und empfängt.

Dieser Beitrag erklärt, was beim Pairing wirklich passiert, wie du das Ergebnis abfragst und was zu tun ist, wenn eine Verbindung erneuert werden muss.

Eine Pairing-Sitzung starten

Das Pairing ist ein zweistufiger API-Ablauf. Zuerst forderst du einen QR-Code an:

POST /v1/accounts/me/pair
Authorization: Bearer <your API key>
Content-Type: application/json

{ "label": "front-desk-phone" }

Die Antwort enthält eine pair_id und ein Feld qr_png_b64, ein Base64-kodiertes PNG, das du direkt in einem Browser oder Admin-Panel anzeigst. Öffne WhatsApp auf dem Handy, das du verbinden möchtest, gehe zu Verknüpfte Geräte → Gerät hinzufügen und scanne den Code genau wie bei WhatsApp Web. Das label ist nur ein lesbarer Name, damit du Geräte später auseinanderhalten kannst, was wichtig wird, sobald du mehr als eines betreibst.

Auf das Ergebnis warten (Polling)

Das Scannen wird aus Sicht der API nicht sofort bestätigt: WhatsApp muss zuerst seinen eigenen Handshake abschließen. Frage den Status-Endpoint ab, bis das Ergebnis feststeht:

async function waitForPairing(pairId, apiKey) {
  const res = await fetch(
    `https://api.textmeflow.eu/v1/accounts/me/pair/${pairId}/status`,
    { headers: { Authorization: `Bearer ${apiKey}` } }
  );
  const { status } = await res.json();
  return status; // "pending" | "connected" | "expired" | "failed"
}

Rufe ihn im Abstand weniger Sekunden von deinem Onboarding-Screen aus auf, bis du connected erhältst (zeige einen Erfolgszustand), expired (der QR-Code ist abgelaufen, bevor er gescannt wurde: fordere einen neuen an) oder failed (auf WhatsApp-Seite ist etwas schiefgegangen: fordere auch hier einen neuen Code an). Ein pending-Ergebnis heißt einfach „weiter warten".

Sobald ein Pairing connected erreicht, ist nichts weiter zu tun: Die Sitzung bleibt bei uns über Neustarts hinweg bestehen, und Nachrichten über /v1/messages oder den /send.php-Kompatibilitäts-Endpoint gehen über diese verbundene Nummer raus, bis sie getrennt wird.

Wie viele Nummern du koppeln kannst

Jeder Tarif koppelt mindestens eine Nummer. Free, Starter und Pro sind Single-Device, Business erlaubt bis zu 3 gleichzeitig gekoppelte Nummern im selben Konto, wodurch es sich für Empfang, Vertriebsleitung und Support-Leitung eignet, die parallel laufen. Wenn du dir unsicher bist, ob du das wirklich brauchst, erklärt die Anleitung zum Multi-Device-Teamsetup, wie Teams den Verkehr üblicherweise auf gekoppelte Nummern verteilen, statt sich ein einziges Postfach zu teilen.

Neu koppeln und abmelden

Zwei Dinge erzwingen ein neues Pairing: Du trennst die Verbindung ausdrücklich, oder das Handy wird aus den WhatsApp-Web-Sitzungen abgemeldet (Zurücksetzen auf Werkseinstellungen, manuelles Trennen am Handy oder die periodische Neuauthentifizierung durch WhatsApp selbst). Um bewusst von deiner Seite zu trennen, etwa beim Wechsel auf eine neue SIM-Karte oder beim Ausmustern eines Geräts, rufst du auf:

DELETE /v1/accounts/me/session

Damit wird die verknüpfte Sitzung sauber beendet. Einen separaten „Entkoppeln"-Schritt gibt es darüber hinaus nicht: Der nächste Aufruf von POST /v1/accounts/me/pair erzeugt einen frischen QR-Code für dasselbe Konto. Beachte, dass das Handy selbst zumindest gelegentlich online und mit dem Internet verbunden bleiben muss: Wie bei WhatsApp Web ist das Pairing eine Sitzung gegen den WhatsApp-Client deines Handys, keine völlig unabhängige Verbindung zu den WhatsApp-Servern.

Praktische Tipps

  • Erzeuge den QR-Code kurz bevor ihn jemand tatsächlich scannt. Sieh expired als normales Ergebnis eines Codes, der über Nacht in einem Browser-Tab offen blieb, nicht als Fehler, den du debuggen musst.
  • Vergib für jedes Gerät ein klares label ("front-desk", "support-line-2"), damit ein Business-Konto mit 3 Nummern später nicht zum Ratespiel wird.
  • Wenn Nachrichten nach Wochen problemlosen Betriebs plötzlich fehlschlagen, prüfe den Pairing-Status, bevor du ein API- oder Kontoproblem vermutest: Ein Handy, das längere Zeit offline war oder auf dem WhatsApp neu installiert wurde, muss neu gescannt werden.

Das Pairing ist ein einmaliger Einrichtungsaufwand pro Gerät, nichts, womit du dich oft beschäftigen wirst, sobald es stabil läuft. Für alles Weitere (Senden, Antworten empfangen, Medien verarbeiten) wirf einen Blick in die Übersicht der Webhook-Events, um zu sehen, wie eingehende Nachrichten dein System erreichen, sobald eine Nummer verbunden ist.

Starte kostenlos auf textmeflow.eu/signup?plan=free: Koppel deine erste Nummer in unter zwei Minuten und sende bis zu 50 Nachrichten pro Monat ohne Kosten.

Selbst WhatsApp-Nachrichten per API senden?

Für immer gratis bis 50 Nachrichten/Monat. QR scannen und in 5 Minuten die erste Nachricht senden.

Für immer gratis