Kopplungscode & QR

Die Kopplung gilt für qr-Verbindungen. Eine cloud_api-Nummer scannt nie etwas und antwortet mit 409 not_supported_for_provider.

Der QR-Weg

POST /connections liefert einen ersten QR-Code als PNG im Data-URI-Format.

Dieselbe Regel gilt für eine idempotente Wiederholung: Wenn POST /connections mit 200 und Idempotency-Replayed: true antwortet, wurde der qr in dieser Antwort frisch abgerufen und nicht aus dem Speicher wiedergegeben – eben weil ein gespeicherter Code nicht mehr scannbar wäre.

Der Weg über den Kopplungscode

Ein QR-Code braucht zwei Geräte: einen Bildschirm, der ihn anzeigt, und ein Telefon, das ihn fotografiert. Ein großer Teil der echten Onboardings findet auf einem Gerät statt – der Kunde schließt Ihren Ablauf auf dem Telefon ab, auf dem auch WhatsApp läuft, und kann den eigenen Bildschirm nicht fotografieren. Für diese Kunden ist der QR-Weg nicht umständlich, sondern unmöglich.

curl -X POST https://developers.wasync.app/api/v1/connections/conn_8f3a21/pairing-code \
  -H "Authorization: Bearer $WASYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"40740267964"}'

{
  "code": "7S59-1KZP"
}

Der Kunde öffnet WhatsApp → Einstellungen → Verknüpfte Geräte → Mit Telefonnummer verknüpfen und gibt den Code ein.

phoneNumber steht im E.164-Format ohne führendes + – nur Ziffern. Alles andere wird mit 400 { "error": "invalid_phone_number" } abgelehnt, statt für Sie bereinigt zu werden: Wer die gesendete Nummer stillschweigend umschreibt, koppelt am Ende ein Konto, das niemand angefordert hat. Verwendet whatsapp.manage, genau wie das Erstellen der Verbindung.

Einen weiteren Code anfordern

Sie können für dieselbe Verbindung einen weiteren Code anfordern: Es wird ein neuer Code zurückgegeben, und die Sitzung wird nicht neu aufgebaut. Eine Schaltfläche „Neuen Code senden“ ist deshalb unbedenklich.

Die Anzahl ist auf 5 pro Verbindung und 15 Minuten begrenzt. Darüber hinaus erhalten Sie 429 { "error": "rate_limited" } mit einem Retry-After-Header, den Sie beachten sollten. Die Begrenzung ist keine Bürokratie – wiederholte Code-Anfragen für eine Nummer sind genau das, worauf die Missbrauchserkennung von WhatsApp reagiert, und gefährdet ist die Nummer Ihres Kunden.

Es wird nichts zusätzlich verbraucht

Die Kopplung per Code belegt denselben bezahlten Platz und startet dieselbe 7-tägige kostenlose Testphase wie das Scannen eines QR-Codes: Die Lizenz wird beansprucht, wenn die Nummer tatsächlich gekoppelt wird – auf welchem Weg auch immer.

Auch die Erfolgskontrolle bleibt unverändert. Es gibt kein Ereignis „Code akzeptiert“. Fragen Sie daher GET /connections/{id} ab, bis status den Wert "connected" hat, und/oder lauschen Sie auf den webhook connection.connected.

Zwei Ablehnungen sollten Sie im Code berücksichtigen:

• 409 already_connected – die Sitzung ist aktiv, es gibt nichts zu koppeln.
• 409 not_supported_for_provider – eine cloud_api-Nummer. Kopplungscodes gibt es nur bei qr, sie gelten hier nie. Versuchen Sie es also nicht erneut.

Später erneut koppeln

Eine qr-Sitzung kann von selbst abbrechen. connection.disconnected teilt es Ihnen mit, und needs_reconnect ist das Feld, an dem Sie Ihre Oberfläche ausrichten sollten. Der QR-Code ist bewusst nicht in dieser Payload enthalten – er ist eine Anmeldedaten-Information zum Scannen. Rufen Sie ihn deshalb über GET /connections/{id} ab und zeigen Sie ihn dem Inhaber der Nummer genau wie bei der Ersteinrichtung an. Siehe Webhooks.