WhatsApp Lookup API: Echtzeit-Registrierungsprüfungen erklärt

Erfahren Sie, wie die WhatsApp Lookup API synchrone Echtzeit-Registrierungsprüfungen, Antwort-Parsing und Workflows für hohe Volumina zur Bereinigung von Kommunikationskanälen handhabt.

Die WA Lookup API bietet synchrone Echtzeit-Verifizierung, um zum Zeitpunkt der Abfrage zu bestätigen, ob eine Telefonnummer bei WhatsApp registriert ist. Durch die Abfrage dedizierter REST-Endpunkte erhalten Teams unmittelbare Signale zur Kontopräsenz innerhalb der initiierenden HTTP-Antwort. Diese Architektur unterstützt Prüfungen einzelner Nummern sowie synchrone Multi-Anfragen und hilft Unternehmen dabei, Routing-Warteschlangen zu bereinigen, Zustellungs-Workflows zu schützen und Nachrichten an nicht zugewiesene Nummern zu vermeiden.

Verständnis von WhatsApp-Registrierungssignalen

Eine Registrierungsprüfung bewertet, ob ein spezifischer Identifikator zum Zeitpunkt der Prüfung ein Konto auf der Plattform unterhält. Dieses Signal zur Plattformpräsenz liefert technischen Kontext zur Erreichbarkeit, bevor eine Kommunikation eingeleitet wird.

Telefonnummern müssen dem internationalen öffentlichen Telekommunikationsformat entsprechen, das in der ITU-T Recommendation E.164 beschrieben ist, welche Ländercodes vorschreibt und die Länge auf 15 Ziffern begrenzt. Die Bewertung von Nummern in der E.164-Struktur standardisiert Eingabedaten über internationale Systeme hinweg.

Aus operativer Sicht informiert die Registrierungsdaten über das Audience-Routing, anstatt Identität, Leitungsbesitz oder die Zustimmung des Empfängers festzustellen. Organisationen, die kommerzielle Outreach-Maßnahmen durchführen, müssen separate Opt-in-Zustimmungsnachweise führen, um die WhatsApp Business Messaging Policy einzuhalten. Die Abstimmung von Kontopräsenzprüfungen mit den Anforderungen zur Datenminimierung gemäß GDPR Article 5 (Regulation (EU) 2016/679) stellt sicher, dass Systeme nur die technischen Erreichbarkeitsindikatoren verarbeiten, die für Zustellungs-Workflows erforderlich sind.

Synchrone Echtzeit-Verifizierungs-Workflows

Die WhatsApp Lookup API stellt synchrone Endpunkte bereit, die für unmittelbare, in-line Entscheidungspipelines konzipiert sind. Da diese Endpunkte synchron arbeiten, erhält die initiierende HTTP-Anfrage Verifizierungsattribute direkt in der Antwort-Payload, ohne dass sekundäre Abfragezyklen erforderlich sind.

Prüfung einzelner Nummern

Für transaktionale Ereignisse wie Registrierungsformulare oder die Erfassung einzelner Leads ruft die Integration POST /api/v1/check unter Verwendung des Authentifizierungs-Headers X-API-Key auf. Die Anfrage übermittelt eine E.164-Telefonnummernfolge und wählt den Ziel-Diensttyp aus.

Synchrone Multi-Prüfung

Wenn Workflows die gleichzeitige Validierung kleinerer Warteschlangen erfordern, akzeptiert POST /api/v1/batch-check bis zu 100 Telefonnummern in einem einzigen Aufruf. Der Endpunkt bewertet die gesamte Charge synchron und gibt den vereinheitlichten Ergebnissatz in der initiierenden Antwort zurück.

Entwickler, die das Anfragevolumen verwalten, sollten die offizielle Dokumentation zu Parametern für Nebenläufigkeit und Timeouts pro Benutzer prüfen, da die Plattform die Kapazität durch Nebenläufigkeitskontrollen und nicht durch feste Anfragelimits pro Minute verwaltet.

Vergleich der Echtzeit-Diensttypen

Die Lookup API strukturiert Registrierungsabfragen in drei spezifische Echtzeit-Diensttypen, um unterschiedliche Anforderungen an Risiko und Anreicherung zu unterstützen.

Die Auswahl von ws liefert den zentralen Erreichbarkeitsindikator. Für Workflows, die eine Profilanreicherung erfordern, fügt ws_avatar die Verfügbarkeit des Profilbilds sowie den gehosteten Bild-Link hinzu, sofern dieser zugänglich ist. Die Option ws_business identifiziert, ob die registrierte Telefonnummer auf der WhatsApp-Business-Plattform betrieben wird, was die Segmentierung zwischen Verbraucher- und Geschäftskonten unterstützt.

Interpretation von Statuscodes und Guthabenverbrauch

Öffentliche API-Antworten formatieren abgeschlossene Prüfungen unter Verwendung von Standard-Envelope-Feldern, die code, msg und data enthalten. Das korrekte Parsen von entschiedenen Ergebnissen gegenüber Dienstfehlern ist entscheidend für zuverlässige Datenpipelines.

Eine abgeschlossene Prüfung erzeugt einen Erfolgs-Antwortcode mit data.registered auf true oder false gesetzt. Sowohl als true als auch als false entschiedene Datensätze stellen abgeschlossene Lookups dar und verbrauchen entsprechend Guthaben.

Ein unbestimmter Status oder eine Unterbrechung des Upstream-Dienstes gibt einen geschäftlichen Code ungleich Null zurück, anstatt einen Wert von registered=false. Downstream-Systeme sollten Codes ungleich Null für eine Wiederholungslogik isolieren, anstatt sie als nicht zugewiesene Telefonnummern zu behandeln. Registrierte Benutzer können den Support kontaktieren, um 100 kostenlose Prüfungen zu erhalten, um die Antwortverarbeitung in Entwicklungsumgebungen zu validieren.

Asynchrone Bulk-Aufgaben für die Listenverarbeitung

Während die synchronen Endpunkte Live-Kundeninteraktionen handhaben, erfordern große Datenmigrationen einen asynchronen Workflow. Für die dateibasierte Validierung verwenden Teams POST /api/v1/bulk-tasks zur Übermittlung von Datensätzen und GET /api/v1/bulk-tasks/{id}, um den Verarbeitungsfortschritt zu verfolgen.

Bulk-Aufgabendateien müssen als TXT- oder CSV-Dokumente übermittelt werden, die eine Telefonnummer pro Zeile enthalten. Die Datei muss sich auf ein einzelnes Zielland konzentrieren, da Listen mit 10 % oder mehr Nummern außerhalb des Ziellandes eine Ablehnung durch die Vorprüfung auslösen. Es gelten produktspezifische Dateilimits, und Teams sollten die offizielle Dokumentation für aktuelle Regeln zur Dateigröße konsultieren.

Die regionale Abdeckung unterscheidet sich ebenfalls zwischen den Workflows. Echtzeit-Prüfungen einzelner Nummern unterstützen Nummern aus Festlandchina (+86), Hongkong (+852) und Macau (+853) bei geringeren Volumina, während asynchrone Bulk-Dateiaufgaben diese Ziele ausschließen. Die Abdeckung für Taiwan bleibt über alle Verarbeitungsmodi hinweg unbestätigt.

FAQ

Wie unterscheiden sich synchrone Echtzeit-Prüfungen von asynchronen Bulk-Aufgaben?

Echtzeit-Prüfungen übermitteln Nummern direkt an POST /api/v1/check oder POST /api/v1/batch-check und liefern Ergebnisse unmittelbar in derselben HTTP-Antwort. Asynchrone Bulk-Aufgaben akzeptieren formatierte Dateien über POST /api/v1/bulk-tasks, geben zuerst eine Aufgaben-ID zurück und generieren nach Abschluss der Verarbeitung eine herunterladbare Ergebnis-CSV.

Wie handhabt die API Gebühren für unbestimmte Prüfungen?

Sowohl registrierte als auch nicht registrierte abgeschlossene Bewertungen verursachen einen Standard-Prüfungsverbrauch. Im Gegensatz dazu gibt ein unbestimmtes Ergebnis oder ein Dienstfehler einen Statuscode ungleich Null anstelle eines falschen Ergebnisses zurück, und fehlgeschlagene Prüfungen verbrauchen kein Guthaben.

Mehr erfahren

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

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