WhatsApp-Checker-API: Registrierungsprüfung aus Ihrem Backend

Wie Backend-Teams eine WhatsApp-Checker-API aufrufen, zwischen der Registrierungs-, Profilbild- und Business-Kontoprüfung wählen und mit unbestimmten Ergebnissen umgehen.

Eine WhatsApp-Checker-API nimmt eine Telefonnummer von Ihrem Server entgegen und gibt in derselben Antwort zurück, ob zum Zeitpunkt der Prüfung ein WhatsApp-Konto für diese Nummer registriert war. Bei WA Lookup wird eine Nummer an POST /api/v1/check gesendet, wobei der Schlüssel im X-API-Key-Header und ein service_type die WhatsApp-Registrierungsprüfung, WhatsApp-Profilbildprüfung oder WhatsApp-Business-Kontoprüfung auswählt. POST /api/v1/batch-check akzeptiert bis zu 100 Nummern in einer synchronen Anfrage. Eine Prüfung, die nicht entschieden werden kann, gibt einen Business-Code ungleich Null zurück, den der Backend-Code als „später erneut versuchen“ und nicht als „Nicht registriert“-Antwort behandeln sollte.

Was eine WhatsApp-Checker-API einem Backend bietet

Suchergebnisse für diese Anfrage sind meist Marktplatz-Angebote und API-Wrapper, die einen Telefonparameter und eine „Wahr“- oder „Falsch“-Antwort anzeigen. Einige davon führen Prüfungen über eine verbundene WhatsApp-Sitzung durch, sodass die API nicht mehr antwortet, wenn das Telefon offline geht. Nur wenige erklären, was die Antwort für den verarbeitenden Code bedeutet oder wie mit Fällen umzugehen ist, in denen keine Antwort möglich ist.

Für die Backend-Arbeit ist das nützliche mentale Modell einfach. Eine WhatsApp-Checker-API beantwortet eine Frage pro Nummer: War zum Zeitpunkt der Prüfung ein WhatsApp-Konto für diese Nummer registriert? Dies ist ein Signal für die Kontopräsenz auf einer Plattform. Es ist ein guter Input für:

• die Entscheidung, ob WhatsApp für einen Kontakt vor einem anderen Kanal ausprobiert werden sollte;
• die Bereinigung eines Telefonfelds in einem CRM oder einer Lead-Datenbank;
• das Hinzufügen von Kontext zu einer Warteschlange für Anmeldungen oder Onboarding-Prüfungen.

Es ist keine Aussage darüber, wer die Nummer besitzt oder ob die Person einer Kontaktaufnahme zugestimmt hat. Bewahren Sie Ihre Zustimmungsnachweise und Kontaktverläufe als separate Eingaben auf und speichern Sie das Datum jeder Prüfung, damit der Wert später aktualisiert werden kann.

So rufen Sie die WhatsApp-Checker-API für eine einzelne Nummer auf

Der Aufruf für eine einzelne Nummer ist eine HTTPS-Anfrage mit einer Antwort. Es muss kein Auftrag erstellt werden, es gibt nichts abzufragen und es muss keine Callback-URL bereitgestellt werden.

1. Normalisierung auf E.164. Senden Sie die Nummer mit einem Pluszeichen, der Landesvorwahl und der nationalen Nummer gemäß dem ITU-T E.164-Nummerierungsplan. Entfernen Sie Leerzeichen, Klammern und nationale Präfixe. Eine deutsche Mobilnummer, die lokal als 0151 2345 6789 geschrieben wird, wird zu +4915123456789. Googles libphonenumber analysiert rohe Eingaben mit einer Standardregion und ist sicherer als manuell geschriebene Regex-Regeln.
2. Wählen Sie die Prüfung. Setzen Sie service_type auf ws, ws_avatar oder ws_business, je nachdem, welche Entscheidung das Ergebnis steuern soll.
3. Authentifizierung vom Server. Senden Sie den Schlüssel im X-API-Key-Header. Laden Sie ihn aus einem sicheren Speicher oder einer Umgebungskonfiguration und platzieren Sie ihn niemals in Browser-Code, einem Mobile-App-Bundle oder einem öffentlichen Repository.
4. Senden Sie POST /api/v1/check. Das Ergebnis für diese Nummer kommt in der Antwort auf dieselbe Anfrage an.
5. Verzweigung nach Ergebnis. Ein abgeschlossenes Ergebnis enthält die Antwort für die ausgewählte Prüfung. Ein Business-Code ungleich Null bedeutet, dass die Prüfung derzeit nicht entschieden werden konnte.

Erstellen Sie den Request-Body und das Response-Parsing gemäß der aktuellen WA Lookup API-Dokumentation. Payloads aus den Beispielen anderer Anbieter unterscheiden sich, und das Kopieren dieser ist eine häufige Quelle für Integrationsfehler.

Wahl des Prüftyps: ws, ws_avatar oder ws_business

Der Wert von service_type bestimmt, welches Signal zurückgegeben wird. Wählen Sie die engste Prüfung, die die Frage Ihres Codes beantwortet, da jede abgeschlossene Prüfung berechnet wird, unabhängig davon, ob die Antwort „Registriert“ oder „Nicht registriert“ lautet.

ws

Die Registrierungsprüfung. Sie teilt dem Backend mit, ob die übermittelte Nummer zum Zeitpunkt der Prüfung ein registriertes WhatsApp-Konto hatte. Dies ist der Standard für Kanalentscheidungen, Listenbereinigungen und Anmeldeüberprüfungen.

ws_avatar

Die Profilbildprüfung. Neben der Registrierung meldet sie, ob ein Profilfoto verfügbar ist, und gibt, falls vorhanden, einen Link dazu an. Der Link kann ein leerer String sein. Verwenden Sie dies zur Anreicherung von Kontaktdaten oder um einem menschlichen Prüfer mehr Kontext zu geben. Ein fehlendes Foto sagt nichts darüber aus, ob die Nummer registriert ist.

ws_business

Die Business-Kontoprüfung. Neben der Registrierung meldet sie, ob es sich um ein WhatsApp-Business-Konto handelt, also den Kontotyp, der mit der WhatsApp Business app oder der Business-Plattform erstellt wurde. Vertriebsteams nutzen dies, um Geschäftskonten von Standardkonten zu trennen. Es beschreibt nur den Kontotyp und ist keine Prüfung auf ein rechtliches Unternehmen.

Prüfung von bis zu 100 Nummern mit dem Batch-Check-Endpunkt

Wenn ein Backend bereits eine Gruppe von Nummern hält, wie bei einem nächtlichen Import oder einer Formulareinreichung mit mehreren Kontakten, sendet POST /api/v1/batch-check bis zu 100 Nummern in einer synchronen Anfrage. Die gesamte Charge kommt in der Antwort auf diese Anfrage zurück, oder die Anfrage schlägt als Ganzes fehl.

Dieses Verhalten prägt den Client-Code:

• Größere Listen stückeln. Teilen Sie die Eingabe in Gruppen von 100 oder weniger auf und senden Sie diese nacheinander oder mit einer kleinen, kontrollierten Anzahl an laufenden Anfragen.
• Fehlgeschlagene Anfrage als Einheit behandeln. Wenn die Batch-Anfrage selbst fehlschlägt, wiederholen Sie diesen Block; markieren Sie die Nummern nicht mit einem Ergebnis.
• Ergebnisse weiterhin pro Nummer lesen. Innerhalb einer erfolgreichen Charge hat jede Nummer ihr eigenes abgeschlossenes oder unbestimmtes Ergebnis, sodass die Verzweigungslogik aus dem Einzelnummern-Ablauf für jeden Eintrag gilt.
• Zuerst deduplizieren. Das Normalisieren vor dem Stückeln deckt oft Duplikate auf, die in verschiedenen lokalen Formaten geschrieben wurden; das einmalige Prüfen jeder Nummer hält die Kosten vorhersehbar.

Der Batch-Endpunkt ist weiterhin ein Ablauf mit direkter Antwort. Er ist das richtige Werkzeug für Dutzende oder einige hundert Nummern, die von Anwendungscode verarbeitet werden, nicht für eine Datei mit einer sehr großen Liste.

Umgang mit unbestimmten Prüfungen und Anfragenfehlern

Der teuerste Integrationsfehler ist das Schreiben von „Nicht registriert“ in eine Datenbank, wenn die Prüfung zu keiner Entscheidung kam. Ein abgeschlossenes „Nicht registriert“-Ergebnis ist eine echte Antwort. Ein Business-Code ungleich Null ist überhaupt keine Antwort.

Ein praktisches Verzweigungsmuster:

Verwenden Sie exponentielles Backoff für Wiederholungsversuche und begrenzen Sie die Anzahl der Versuche, damit ein vorübergehendes Problem nicht zu einer Flut von wiederholten Anrufen führt. Halten Sie die unbestimmten Nummern in einem separaten Status wie „Wartet auf erneute Prüfung“, wodurch Berichte sie von entschiedenen Ergebnissen unterscheiden können.

Betrieb der Integration in der Produktion

Einige Betriebsgewohnheiten machen eine Checker-Integration einfacher zu unterstützen:

• Dokumentierte Kontrollen respektieren. Die aktuelle API-Dokumentation beschreibt die Parallelitäts- und Timeout-Kontrollen pro Benutzer. Passen Sie die Anzahl der laufenden Anfragen an diese Kontrollen an und lesen Sie die Dokumentation erneut, wenn Sie skalieren, anstatt von einer festen erlaubten Anzahl pro Minute auszugehen.
• Kontostand im Auge behalten. Ein Kontostand deckt das Dashboard, die REST-API und den MCP-Server ab, sodass ein großer API-Job und manuelle Dashboard-Prüfungen aus demselben Pool schöpfen. Prüfen Sie den Kontostand im Dashboard vor einem großen Durchlauf.
• Protokollieren ohne Lecks. Protokollieren Sie Ergebnisausgänge und Fehlercodes, aber maskieren Sie Telefonnummern in allgemeinen Anwendungsprotokollen und protokollieren Sie niemals den API-Schlüssel.
• Schlüssel rotieren. Das Dashboard verwaltet API-Schlüssel; rotieren Sie einen Schlüssel, wenn er möglicherweise offengelegt wurde, und aktualisieren Sie den geheimen Speicher in einem Schritt.
• Kontext aufzeichnen. Speichern Sie, welche Prüfung wann durchgeführt wurde. Ein Ergebnis von vor Monaten beschreibt die Nummer zu diesem Zeitpunkt, nicht heute.

Die Nutzungsbedingungen von WhatsApp schränken den automatisierten oder nicht autorisierten Zugriff auf seine Dienste ein, was ein Grund dafür ist, dass Teams von Skripten, die eine persönliche Sitzung steuern, zu einer gehosteten API mit eigenem Schlüssel übergehen.

Wann eine Datei-Aufgabe besser passt als die API

Für eine sehr große Liste ist eine asynchrone Bulk-Aufgabe die bessere Wahl: Laden Sie eine TXT- oder CSV-Datei mit einer Nummer pro Zeile hoch, warten Sie auf die Verarbeitung und laden Sie dann eine result.csv herunter. Bulk-Aufgaben verwenden POST /api/v1/bulk-tasks zum Einreichen und GET /api/v1/bulk-tasks/{id}, um den Fortschritt zu verfolgen; es gelten die produktbezogenen Limits, wie in der API-Dokumentation beschrieben. Die Datei sollte Nummern aus im Wesentlichen einem Land enthalten, und die Bulk-Dienste decken keine Nummern aus Festlandchina, Hongkong oder Macau ab. Das Bulk-Guthaben wird bei der Einreichung reserviert, wobei der nicht genutzte Teil nach der Verarbeitung zurückgegeben wird.

Für die meisten Backend-Funktionen, die auf eine Benutzeraktion oder einen kleinen Import reagieren, bleiben die synchronen Einzel- und Batch-Check-Aufrufe die einfachere Wahl.

FAQ

Wie können Teams eine WhatsApp-Checker-API testen, bevor sie sie in die Produktion integrieren?

Beginnen Sie mit einer Handvoll Nummern, deren erwartetes Ergebnis das Team bereits kennt, wie z. B. Firmentelefone, und rufen Sie den Einzelnummern-Endpunkt aus einer Staging-Umgebung auf. Berechtigte neue Konten erhalten nach der Registrierung einmalig 100 kostenlose Prüfungen, was normalerweise ausreicht, um die Pfade für „Registriert“, „Nicht registriert“ und „Wiederholungsversuch“ im Client-Code zu testen.

Was sollte ein Backend tun, wenn eine Nummer als unbestimmt zurückgegeben wird?

Lassen Sie das Ergebnisfeld leer, protokollieren Sie den Business-Code und die Zeit und stellen Sie die Nummer in eine Wiederholungswarteschlange mit Backoff. Das Schreiben eines „Nicht registriert“-Werts für eine unbestimmte Prüfung korrumpiert Listendaten und führt später zu falschen Kanalentscheidungen.

Funktioniert der Batch-Check-Endpunkt anders als ein Datei-Upload?

Ja. Der Batch-Check-Endpunkt gibt bis zu 100 Ergebnisse in der Antwort auf dieselbe Anfrage zurück. Ein Datei-Upload erstellt eine asynchrone Bulk-Aufgabe, die im Hintergrund verarbeitet wird, wonach eine result.csv heruntergeladen wird.

Welchen Prüftyp sollte eine CRM-Integration standardmäßig verwenden?

Die Registrierungsprüfung, ws, deckt die meisten Kanal- und Datenqualitätsentscheidungen ab. Fügen Sie ws_avatar oder ws_business nur hinzu, wenn ein Feld im CRM tatsächlich die Profilbildverfügbarkeit oder den Kontotyp verwendet, da jede abgeschlossene Prüfung berechnet wird.

Mehr erfahren

Wählen Sie die Produktinformationen, die zum nächsten Schritt in Ihrem Workflow passen.

• Produkt-Dokumentation ansehen →
• Mit dem Team sprechen →