WA Lookup
Eine Telefonnummer durchläuft eine synchrone Pipeline zur Registrierungsprüfung bis zu einem abgeschlossenen Ergebnis
Eine Anfrage führt eine normalisierte Nummer durch die Validierung und liefert ein Registrierungsergebnis.

Was „Echtzeit“ bei diesem Produkt bedeutet

Echtzeit bedeutet, dass die Registrierungsentscheidung in derselben HTTP-Anfrage zurückgegeben wird statt über einen Hintergrundjob, einen Webhook oder einen späteren Export.

Der Aufrufer sendet eine normalisierte Telefonnummer und wartet auf die Antwort. Ist die Prüfung abgeschlossen, meldet data.registered, ob diese Nummer zum Zeitpunkt der Anfrage bei WhatsApp registriert war. Der Aufrufer kann das Ergebnis sofort verwenden, ohne einen weiteren Endpunkt abzufragen.

Das ist ein eng gefasster Produktvertrag. WA Lookup prüft den Registrierungsstatus; es identifiziert nicht die Person hinter der Nummer, überwacht keine Kontoaktivität und betreibt keinen Messaging-Dienst. Wenn dieser Umfang klar benannt bleibt, lässt sich das zurückgegebene Feld leichter korrekt verwenden.

Zurückgegebene Daten Bedeutung Empfohlene Aktion
code=0, registered=true Die abgeschlossene Prüfung meldete „registriert“ Verwenden Sie das von dieser Anfrage zurückgegebene boolesche Ergebnis
code=0, registered=false Die abgeschlossene Prüfung meldete „nicht registriert“ Verwenden Sie false als abgeschlossenes Ergebnis
Business-Code ungleich null Der Dienst lieferte keine Registrierungsentscheidung Erfinden Sie keinen booleschen Wert; behandeln Sie den Fehler oder wiederholen Sie die Anfrage gemäß der API-Dokumentation

Warum synchrone Prüfungen nützlich sind

Ein synchrones Ergebnis ist nützlich, wenn der nächste Softwareschritt von einer aktuellen Registrierungsantwort abhängt. Die Anwendung muss keinen Job anlegen, kein Polling-Token speichern und nicht auf einen Callback warten, bevor sie die Nummer klassifizieren kann.

Typische Integrationen sind ein internes Formular, das eine Nummer prüft, ein Support-Tool, das einen Datensatz bei Bedarf verifiziert, oder ein Backend-Worker. Für kleine Listen akzeptiert der synchrone Batch-Endpunkt bis zu 100 E.164-Kennungen und liefert den abgeschlossenen Batch in der auslösenden Antwort zurück. Clients sollten ihre Parallelität dennoch selbst steuern.

Der wichtigste architektonische Vorteil ist Determinismus: Eine abgeschlossene Antwort enthält genau eine boolesche Registrierungsentscheidung. API-Fehler und unbestimmte Prüfungen nutzen den äußeren Umschlag aus code, msg und data, statt registered um weitere Werte zu ergänzen.

Der Anfrageweg Schritt für Schritt

  1. Telefonnummer normalisieren – Wandeln Sie eine eindeutig bekannte Ländervorwahl und nationale Nummer in das E.164-Format um. Raten Sie fehlenden Länderkontext nicht.
  2. Eine Prüfung senden – Rufen Sie den authentifizierten Prüf-Endpunkt mit der normalisierten Nummer und service_type=ws auf.
  3. Abgeschlossenes Ergebnis lesen – Verarbeiten Sie data.registered, wenn code=0 ist; lassen Sie den Wert leer, wenn die API einen Business-Code ungleich null zurückgibt.
  4. Beobachtungszeitpunkt speichern – Die Registrierung ist ein Ergebnis zu einem bestimmten Zeitpunkt, speichern Sie also, wann geprüft wurde.
  5. Nicht-Ergebnisse getrennt behandeln – Eine ungültige Anfrage oder ein vorübergehender Fehler erfordert Korrektur oder Wiederholung, keinen Registrierungswert false.

Das Ergebnis modellieren, ohne Bedeutung zu verlieren

Vermeiden Sie ein generisches Feld wie valid. Es kann eine fehlerhafte Eingabe nicht von einer gültigen Nummer unterscheiden, deren Prüfung mit „nicht registriert“ abgeschlossen wurde. Ein kleiner, expliziter Datensatz ist sicherer:

Feld Zweck
source_phone Bewahrt den vom Quellsystem gelieferten Wert
e164_phone Speichert die kanonische Nummer, die zur Prüfung übermittelt wurde
outcome Die Klassifizierung Ihrer Anwendung: abgeschlossen, wiederholbar oder fehlgeschlagene Anfrage
registered Speichert true oder false nur für eine abgeschlossene Prüfung
checked_at Hält fest, wann die zeitpunktbezogene Beobachtung erfolgte
service_type Hält fest, welcher Produktvertrag das Ergebnis erzeugt hat

HTTP-Fehler sind keine zusätzlichen Werte für diesen Datensatz. Wenn eine Anwendung sie protokolliert, sollte sie den zurückgegebenen HTTP-Status und den API-code getrennt von den Registrierungsbeobachtungen speichern.

Eine praktische Integrationsregel

Verzweigen Sie nur dann anhand von data.registered, wenn die äußere Antwort code=0 enthält.

Diese eine Regel verhindert den häufigsten Interpretationsfehler: ein Timeout, eine abgelehnte Anfrage oder eine fehlerhafte Nummer so zu behandeln, als hätte WhatsApp die Nummer als nicht registriert gemeldet. Muss die Entscheidung zu einem späteren Zeitpunkt aktuell sein, führen Sie eine neue synchrone Prüfung durch und speichern Sie sie als neue Beobachtung, statt den alten Zeitstempel stillschweigend zu ändern.

Quellen