Die WA Lookup API zur Anreicherung von WhatsApp-Profilen integrieren

Ein technischer Leitfaden für Entwickler zur Implementierung synchroner WhatsApp-Profil- und Avatar-Abfragen mit der WA Lookup API.

Die WA Lookup API bietet eine synchrone REST-Schnittstelle, mit der Entwickler die Anreicherung von WhatsApp-Profilen automatisieren können. Wenn Sie eine POST-Anfrage an den Endpunkt /api/v1/check mit einem bestimmten Diensttyp – ws, ws_avatar oder ws_business – und einer Telefonnummer im E.164-Format senden, liefert die API sofort Kontopräsenzsignale direkt in der HTTP-Antwort. Zu diesen Signalen gehören der Registrierungsstatus, die Verfügbarkeit eines Avatars, Avatar-URLs und Hinweise auf ein Business-Konto. Sie können als Eingaben für CRM-Routing, Zielgruppensegmentierung und interne Workflows zur Entscheidungsunterstützung dienen.

Einführung in die WA Lookup API

Wenn technische Teams Kommunikationskanäle in Geschäftsabläufe integrieren, benötigen sie genaue Kontopräsenzsignale für ihre Routing- und Segmentierungslogik. WA Lookup bietet synchrone Einzel- und Kleinbatch-Prüfungen für WhatsApp-Registrierung, Avatar-Verfügbarkeit und den Status als Business-Konto. Der Einzel-Endpunkt prüft eine Kennung, der synchrone Multi-Endpunkt akzeptiert bis zu 100 Kennungen; beide liefern die Daten in derselben HTTP-Antwort. Diese synchrone Architektur ermöglicht sofortige Entscheidungen ohne asynchrone Webhooks, Polling-Infrastruktur oder Warteschlangen für die Stapelverarbeitung. Es ist entscheidend, die Grenzen dieses Kontopräsenzsignals zu verstehen. Ein Ergebnis „registriert“ gibt die WhatsApp-Statusfelder wieder, die genau zum Zeitpunkt der Prüfung verfügbar sind. Es sagt nichts über die Live-Präsenz, den Nachrichtenverlauf, die Einwilligung des Nutzers oder darüber aus, ob die Nummer derzeit kontaktiert werden kann. Vielmehr trägt es zu einem umfassenderen Workflow bei und hilft Teams, Datensätze zu prüfen und die Ansprache anhand der Plattformpräsenz zu priorisieren.

Die Diensttypen verstehen

Die WA Lookup API bündelt ihre Funktionen in einem einzigen synchronen Endpunkt. Über den Parameter service_type in der Anfrage steuern Entwickler, welche Profilsignale abgerufen werden – und welche Guthabenkosten anfallen. Die API unterstützt drei verschiedene Diensttypen:

• WhatsApp Checker (ws): Dies ist der grundlegende Diensttyp. Sein Umfang beschränkt sich strikt darauf, zu bestätigen, ob eine übermittelte Telefonnummer bei WhatsApp registriert ist. Er liefert ein einfaches Signal zur Plattformregistrierung.
• WhatsApp Avatar Checker (ws_avatar): Dieser Diensttyp erweitert die Basisprüfung um eine Profilanreicherung. Zusätzlich zur WhatsApp-Registrierung prüft er, ob ein Avatar verfügbar ist, und gibt ein Feld avatar_url zurück. Das URL-Feld ist leer, wenn keine URL verfügbar ist.
• WhatsApp Business Checker (ws_business): Dieser Diensttyp ist auf B2B-Workflows zugeschnitten. Er prüft die normale WhatsApp-Registrierung und ermittelt zusätzlich, ob das Konto WhatsApp Business nutzt, und liefert so ein spezifisches Signal zum Business-Profil.

Durch die Wahl des passenden Diensttyps können technische Produktmanager die Ausgabe der API genau an ihre Workflow-Anforderungen anpassen und sicherstellen, dass sie nur die Daten anfordern und verbrauchen, die für ihren konkreten Anwendungsfall notwendig sind.

Technische Implementierung

Die Integration der WA Lookup API erfordert die Einhaltung eines strikten JSON-Anfragevertrags und fester Formatierungsregeln. Alle Interaktionen erfolgen über den Endpunkt POST /api/v1/check. Um die Anfrage korrekt zu authentifizieren und zu formatieren, müssen Entwickler bestimmte Header mitsenden: den Header X-API-Key mit dem aktiven API-Schlüssel sowie den Header Content-Type: application/json. Der JSON-Body der Anfrage muss genau zwei Felder enthalten:

1. service_type: Ein String mit dem Wert "ws", "ws_avatar" oder "ws_business".
2. identifier: Die Zieltelefonnummer, strikt im E.164-Format übermittelt.

Das E.164-Format ist ein internationaler Rufnummernplan, der sicherstellt, dass Telefonnummern weltweit eindeutig sind. Eine Nummer im E.164-Format muss mit einem Pluszeichen (+) beginnen, unmittelbar gefolgt von der Ländervorwahl und der Teilnehmernummer, ohne Leerzeichen, Bindestriche oder Klammern (z. B. +17253100591). Wird das E.164-Format nicht verwendet, schlägt die Prüfung fehl. Da die API vollständig synchron arbeitet, bleibt die HTTP-Verbindung geöffnet, während die Prüfung läuft, und die Ergebnisse werden in der unmittelbaren HTTP-Antwort geliefert.

API-Antworten interpretieren

Die WA Lookup API liefert in jeder Prüfantwort einen vorhersehbaren Satz von Feldern; je nach gewähltem service_type kommen weitere Felder hinzu. 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. Ist service_type auf ws gesetzt, enthält das Ergebnis neben den zurückgegebenen Werten service_type und identifier nur das Feld registered. Ist service_type auf ws_avatar gesetzt, wird das Antwortschema um ein Feld avatar (ein boolescher Wert, der angibt, ob ein Avatar gesetzt ist) und ein Feld avatar_url erweitert. avatar_url ist ein leerer String, wenn keine URL verfügbar ist. Ist service_type auf ws_business gesetzt, ergänzt das Antwortschema ein Feld business, einen booleschen Wert, der angibt, ob die registrierte Nummer mit einem WhatsApp Business-Konto verknüpft ist.

Dashboard und Nutzungsverwaltung

Die Verwaltung der API-Nutzung und die Überwachung der Workflow-Eingaben erfolgen über das Dashboard der Plattform. Das Dashboard bietet umfassende Unterstützung bei der Verwaltung von API-Schlüsseln, sodass Entwickler die für den Header X-API-Key benötigten Schlüssel sicher erzeugen und rotieren können. Für die operative Übersicht bietet das Dashboard Funktionen zur Guthabenverfolgung, zur Einsicht in den Prüfverlauf und zum Zugriff auf Berichte auf Produktebene. Technische Teams können aktuelle Prüfungen überwachen, Guthabenausgaben analysieren und Kontoaktivitäten einsehen, um ihre Nutzungsmuster zu verstehen und ihre Integration zu optimieren. Prüfen Sie Guthaben und Prüfverlauf im Dashboard; die aktuellen Abrechnungsregeln finden Sie auf der Preisseite und in der API-Dokumentation.

FAQ

Ist die WA Lookup API synchron?

Ja. Die Echtzeit-Endpunkte sind synchron: Die Ergebnisse werden in derselben HTTP-Antwort wie die auslösende Anfrage zurückgegeben. Der Einzelnummer-Endpunkt prüft eine Kennung, und der synchrone Multi-Endpunkt akzeptiert bis zu 100 Kennungen – ohne Jobs, Callbacks oder Polling. Größere Listen werden von einem separaten asynchronen Massenprüfungsprodukt verarbeitet, bei dem Sie eine Datei hochladen und das Ergebnis später herunterladen.

Was ist der Unterschied zwischen den Diensttypen ws und ws_avatar?

Der Diensttyp ws liefert nur das grundlegende Signal zur WhatsApp-Registrierung. Der Diensttyp ws_avatar liefert das Registrierungssignal und prüft zusätzlich, ob ein Avatar verfügbar ist; er gibt einen String avatar_url zurück, der leer ist, wenn keine URL verfügbar ist.

Welches Format müssen Telefonnummern haben?

Alle an die API übermittelten Telefonnummern müssen gemäß dem E.164-Standard formatiert sein. Dafür ist ein Pluszeichen (+) erforderlich, gefolgt von der Ländervorwahl und der Teilnehmernummer, ohne Leerzeichen oder Sonderzeichen.