WA Lookup integrieren: Automatisierte CRM-Datenhygiene und Kontoklassifizierung

Erfahren Sie, wie Sie die synchrone WA Lookup API integrieren, um die WhatsApp-Kontopräsenz zu prüfen, Avatar-Details abzurufen und Business-Konten für die CRM-Datenhygiene zu klassifizieren.

Die WA Lookup API ermöglicht CRM-Systemen eine synchrone Prüfung der WhatsApp-Kontopräsenz. Indem Entwickler eine POST-Anfrage mit einer Telefonnummer im E.164-Format an den Endpunkt /api/v1/check senden, können sie Registrierungsstatus, Avatar-Verfügbarkeit oder Business-Kontoklassifizierung in derselben HTTP-Antwort abrufen. Diese Daten helfen, die CRM-Hygiene zu wahren, indem sie gültige, mit WhatsApp verknüpfte Datensätze erkennen – ohne asynchrone Verarbeitung, Polling oder Webhooks.

Die Architektur der WA Lookup API verstehen

Die Integration von Signalen zur Kontopräsenz in ein CRM erfordert eine Architektur, die sofortiges Daten-Routing und unmittelbare Entscheidungen unterstützt. Die WA Lookup API ist um einen einzigen synchronen Endpunkt herum aufgebaut: POST /api/v1/check. Wenn ein CRM-System oder eine Data-Operations-Plattform eine Anfrage übermittelt, verarbeitet die API die Prüfung und liefert die Ergebnisse in derselben HTTP-Antwort. Diese synchrone Architektur beseitigt den Entwicklungsaufwand asynchroner Verarbeitung, etwa das Konfigurieren von Webhooks, das Verwalten von Callback-URLs oder das Implementieren von Polling-Logik. Entwickler können die API direkt in synchrone Workflows integrieren, etwa in Formulare zur Lead-Erfassung oder in Pipelines zur Datenbereinigung in Echtzeit. Bei einer abgeschlossenen WhatsApp-Prüfung enthält das zurückgegebene data die Felder service_type, identifier und registered; ws_avatar enthält zusätzlich avatar und avatar_url, während ws_business das Feld business enthält. Interne Datensatz-, Transaktions-, Status- und Abrechnungsfelder werden nicht zurückgegeben.

WhatsApp-Kontotypen klassifizieren

Um unterschiedliche Anforderungen an die CRM-Datenhygiene zu erfüllen, bietet die Echtzeit-API drei verschiedene Service-Typen. Alle drei nutzen denselben synchronen Endpunkt, wobei der Parameter service_type steuert, welche Felder in der Antwort zurückgegeben werden und welche Guthabenkosten für die Transaktion gelten.

Service-Typen im Vergleich

Der WhatsApp Checker (ws) ist der grundlegende Service-Typ. Er dient ausschließlich dazu, zu bestätigen, ob eine übermittelte Telefonnummer bei WhatsApp registriert ist, und gibt nur das Feld registered zurück. Er wird typischerweise für die einfache Listenbereinigung genutzt und um zu erkennen, welche CRM-Kontakte ein WhatsApp-Konto haben. Der WhatsApp Avatar Checker (ws_avatar) erweitert die einfache Prüfung um Funktionen zur Profilanreicherung. Zusätzlich zum Registrierungsstatus liefert er einen booleschen Wert avatar, der angibt, ob ein Profilbild gesetzt ist, sowie einen String avatar_url. Das URL-Feld ist leer, wenn keine URL verfügbar ist. Dieses Signal kann Teams helfen, die Vollständigkeit eines Kontaktprofils zu beurteilen. Der WhatsApp Business Checker (ws_business) ist für die B2B-Segmentierung im CRM konzipiert. Er prüft die WhatsApp-Registrierung und liefert einen booleschen Wert business, der angibt, ob das Konto WhatsApp Business nutzt. So können Data-Operations-Manager private Konten und Business-Konten in ihren Datenbanken voneinander trennen.

Technische Implementierung und Datenhygiene

Die Integration der API in ein CRM oder eine Datenpipeline erfordert die Einhaltung des dokumentierten Anfragevertrags. Die API erwartet eine JSON-Nutzlast und bestimmte Header, um die Anfrage zu authentifizieren und erfolgreich zu verarbeiten. Der dokumentierte Anfragevertrag verlangt eine POST-Anfrage an /api/v1/check. Die Anfrage muss zwei Header enthalten: X-API-Key mit Ihrem Authentifizierungsschlüssel und Content-Type: application/json. Der JSON-Body muss genau zwei Felder enthalten:

1. service_type: Ein String-Wert ws, ws_avatar oder ws_business.
2. identifier: Die zu prüfende Telefonnummer.

Entscheidend ist, dass alle übermittelten Telefonnummern gemäß dem internationalen Rufnummernplan E.164 formatiert sind. Eine US-Nummer muss beispielsweise als +17253100591 übermittelt werden. Wird das E.164-Format nicht verwendet, kann dies zu Parsing-Fehlern oder unbestimmten Prüfungen führen. Ein typischer JSON-Body sieht so aus: {"service_type": "ws_business", "identifier": "+17253100591"} Indem Entwickler CRM-Eingaben auf E.164 standardisieren und über diese synchrone Prüfung leiten, können sie ungültige Nummern automatisch markieren, Business-Nutzer segmentieren und einen hohen Standard der Datenhygiene wahren. Da die Antwort sofort vorliegt, lassen sich diese Prüfungen direkt in Dateneingabeformulare integrieren, sodass nur verifizierte Signale zur Kontopräsenz in die Datenbank übernommen werden.

Dashboard-Berichte und Kontoverwaltung

Die Verwaltung der API-Nutzung und die Überwachung der Datenhygiene erfolgen über das Plattform-Dashboard. Das Dashboard bietet CRM-Administratoren und Entwicklern umfassende Werkzeuge, um die Leistung ihrer Integration zu verfolgen und die Authentifizierung zu verwalten. Das Dashboard unterstützt eine vollständige Verwaltung der API-Schlüssel, sodass Teams Schlüssel sicher rotieren können. Für die operative Kontrolle bietet es Einblick in das aktuelle Kontoguthaben, einen detaillierten Prüfverlauf und Berichte auf Produktebene. Administratoren können aktuelle Prüfungen einsehen, den Guthabenverbrauch überwachen und die Kontoaktivität analysieren, um zu verstehen, wie die API in verschiedenen CRM-Workflows genutzt wird. Bei einer abgeschlossenen WhatsApp-Prüfung enthält das zurückgegebene data die Felder service_type, identifier und registered; ws_avatar enthält zusätzlich avatar und avatar_url, während ws_business das Feld business enthält. Interne Datensatz-, Transaktions-, Status- und Abrechnungsfelder werden nicht zurückgegeben.

FAQ

Ist die WA Lookup API synchron oder asynchron?

Die WA Lookup API ist strikt synchron. Wird eine Anfrage an den Endpunkt POST /api/v1/check übermittelt, werden die Ergebnisse in derselben HTTP-Antwort wie die Anfrage zurückgegeben.

Kann diese API prüfen, ob ein Nutzer gerade online ist?

Nein. Ein Ergebnis „registriert“ meldet die WhatsApp-Statusfelder, die zum Zeitpunkt der Prüfung verfügbar waren. Es dient ausschließlich als Signal zur Kontopräsenz und gibt keine Auskunft über Live-Präsenz, Nachrichtenverlauf, Einwilligung des Kontakts oder darüber, ob die Nummer derzeit kontaktiert werden kann.

Was ist der Unterschied zwischen den Service-Typen ws, ws_avatar und ws_business?

Alle drei Service-Typen nutzen denselben synchronen Endpunkt, liefern aber unterschiedliche Felder. Der Service-Typ ws bestätigt die grundlegende WhatsApp-Registrierung. Der Service-Typ ws_avatar liefert den Registrierungsstatus zusammen mit einem booleschen Wert avatar und einem Avatar-URL-Feld, das leer ist, wenn keine URL verfügbar ist. Der Service-Typ ws_business liefert den Registrierungsstatus und einen booleschen Wert, der angibt, ob das Konto WhatsApp Business nutzt.