WhatsApp-Profilbild-API: Echtzeit-Avatar-Analyse nach Telefonnummer

Ein Entwicklerhandbuch für WhatsApp-Profilbild-APIs: Was URL-basierte Tools zurückgeben, wie sich die Echtzeit-Einzelabfragen und synchronen Mehrfachabfragen von AvatarLookup unterscheiden und wie Ergebnisse gespeichert und erneut angefordert werden.

Eine WhatsApp-Profilbild-API nimmt eine Telefonnummer entgegen und liefert Informationen über das öffentliche Profilbild, das mit dieser Nummer verknüpft ist. Viele Tools beschränken sich auf eine temporäre Bild-URL, die Sie selbst herunterladen und interpretieren müssen. Die WhatsApp-Profilbildanalyse von AvatarLookup liefert stattdessen ein strukturiertes Ergebnis: eine Echtzeit-Einzelprüfung über POST /api/v1/check oder eine synchrone Mehrfachprüfung über POST /api/v1/batch-check mit 1–100 Nummern pro Anfrage. Erscheinungsmerkmale im Ergebnis sind algorithmische Schätzungen. Es werden nur öffentliche Avatare analysiert; wenn ein Kontakt sein Foto auf gespeicherte Kontakte beschränkt, wird kein öffentliches Bild angezeigt. Ein Ergebnis vom Typ Unbestimmt sollte später erneut angefordert werden, anstatt es als endgültiges Urteil über das Konto zu interpretieren.

Drei Arten von WhatsApp-Profilbild-APIs

Suchergebnisse für diesen Begriff vermischen drei verschiedene Dinge. Die Wahl des falschen Typs verschwendet Integrationszeit.

Die offiziellen Business-Einstellungen dienen dem Foto Ihres eigenen Kontos, nicht dem Nachschlagen anderer Nummern. URL-basierte Tools geben Links zurück, die häufig ablaufen, sodass Teams die Bilder selbst herunterladen, speichern und kennzeichnen müssen. Die Bild-Profilanalyse überspringt den Schritt der Bildverarbeitung und liefert Daten, die in einen Kontaktdatensatz passen. Alle drei Typen unterliegen derselben Regel: Das Foto muss öffentlich sichtbar sein.

Echtzeit-Einzelprüfung mit POST /api/v1/check

Verwenden Sie die Einzelprüfung, wenn eine Nummer innerhalb eines interaktiven Ablaufs eine Antwort erfordert, beispielsweise wenn ein Support-Mitarbeiter einen Kontaktdatensatz öffnet.

1. Nummer normalisieren. Konvertieren Sie die Nummer in das internationale Format mit Ländervorwahl gemäß der Struktur der ITU-T Recommendation E.164 und entfernen Sie Leerzeichen, Bindestriche und Klammern.
2. Senden Sie eine authentifizierte Anfrage an POST /api/v1/check unter Angabe des WhatsApp-Avatar-Produkts und der Nummer. Befolgen Sie die API-Dokumentation für den exakten Anfragetext; raten Sie keine Feldnamen.
3. Lesen Sie die Antwort einmalig aus und speichern Sie diese zusammen mit dem Prüfdatum und einer Quellenkennzeichnung für WhatsApp.
4. Verzweigen Sie basierend auf dem Ergebnis: Profilbild verfügbar, Kein Profilbild oder Unbestimmt.

Halten Sie den Aufruf außerhalb von blockierenden Pfaden, auf die ein Kunde warten muss. Wenn die Prüfung langsam oder unbestimmt ist, sollte der Datensatz dennoch gespeichert werden, wobei die Avatar-Felder leer bleiben und ein Hinweis auf eine notwendige spätere Prüfung gesetzt wird. Nummern aus Festlandchina, Hongkong und Macau werden nur über Echtzeit-Einzelprüfungen unterstützt; leiten Sie diese daher hierhin und nicht in Bulk-Dateien.

Synchrone Mehrfachprüfung mit POST /api/v1/batch-check

Die Mehrfachprüfung verarbeitet eine kurze Liste in einem einzigen Aufruf. Jede Anfrage akzeptiert 1–100 Identifikatoren eines Produkttyps und gibt Ergebnisse als geordnetes JSON zurück, das der Reihenfolge Ihrer Eingabe entspricht.

Praktische Regeln für Mehrfachanfragen:

• Produkte nicht mischen. Senden Sie WhatsApp-Nummern in einer Anfrage und unterstützte E-Mail-Adressen von Gmail, Yandex oder Mail.ru in einer anderen.
• Auf Reihenfolge verlassen, dann verifizieren. Die Ergebnisse folgen der Eingabereihenfolge; ordnen Sie dennoch jedes Ergebnis der entsprechenden Eingabenummer zu, bevor Sie es in Ihre Datenbank schreiben.
• Längere Listen unterteilen. Teilen Sie eine Liste von 350 Nummern in vier Anfragen mit jeweils bis zu 100 Nummern auf.
• Bulk-Aufgaben für große Dateien nutzen. Wenn eine Liste deutlich umfangreicher ist, akzeptiert das asynchrone WhatsApp-Bulk-Produkt eine TXT- oder CSV-Datei und gibt eine CSV-Datei für die Aufgabe zurück.

Nicht-technische Teams können das Dashboard verwenden, das bis zu 500 Identifikatoren akzeptiert und diese nacheinander verarbeitet. In jedem Fall verfügen nur WhatsApp und die unterstützten E-Mail-Domains über Echtzeit- und Mehrfachprüfungen; Telegram, Viber, MAX, LINE und Zalo sind reine Bulk-Produkte.

Umgang mit unbestimmten Ergebnissen und Ergebnissen ohne Profilbild

Die meisten Integrationsfehler entstehen, wenn verschiedene Ergebnisse in einem einzigen leeren Wert zusammengefasst werden. Halten Sie diese getrennt:

• Ergebnis produziert. Die Mehrfachantwort markiert jedes Element, für das ein Ergebnis produziert wurde. Dieser Status bedeutet, dass ein Ergebnis für die Anfrage vorliegt, nicht, dass das WhatsApp-Konto existiert.
• Ergebnis nicht produziert. Dies umfasst ungültige, unbestimmte oder fehlgeschlagene Elemente. Es ist kein negatives Urteil über das Konto oder dessen Avatar; planen Sie daher eine spätere Wiederholung ein, anstatt den Kontakt zu löschen.
• Kein Profilbild. Ein abgeschlossenes Ergebnis kann zeigen, dass kein öffentliches Bild verfügbar ist. Die Datenschutzeinstellungen von WhatsApp erlauben es Benutzern, ihr Profilfoto für „Jeder“, „Meine Kontakte“, „Meine Kontakte außer...“ oder „Niemand“ freizugeben. Ein fehlendes öffentliches Bild ist daher oft nur eine Entscheidung der Privatsphäre.

Schreiben Sie jeden Status in seinen eigenen Wert, wie z. B. verfügbar, keine oder wiederholen, und protokollieren Sie den Grund für Wiederholungen. Ein sauberes Zustandsmodell macht auch die Berichterstattung korrekt: Eine Dashboard-Zählung von „Kein Profilbild“ sollte niemals Elemente enthalten, die lediglich unbestimmt waren.

Speichern von Ergebnissen als Schätzungen

Erscheinungsmerkmale wie Bildtyp, Altersspanne oder Haarfarbe beschreiben das Bild, nicht die Person hinter der Nummer. Ein Cartoon, ein Haustier, ein Logo oder ein Gruppenfoto können gültige Profilbilder sein, und deren Analyse ist dennoch ein vollständiges Ergebnis.

Ein einfaches Speichermuster:

Halten Sie diese Felder aus Entscheidungen über Berechtigungen, Kreditwürdigkeit, Einstellungsprozesse oder Preisgestaltung heraus sowie aus jeglichen Prüfungen, die Personen aufgrund geschätzter Alters- oder Geschlechtsmerkmale unterschiedlich behandeln. Ein öffentlicher Avatar ist ein Signal für Kontaktdaten; er verifiziert weder Identität, Kontoinhaberschaft noch die Zustimmung zur Kontaktaufnahme. Legen Sie ein Überprüfungsintervall fest, da Benutzer ihre Bilder ändern, und löschen Sie veraltete Schätzungen gemäß Ihrer normalen Aufbewahrungsrichtlinie.

FAQ

Wie können Teams die eigentliche Bilddatei anstelle von Analysefeldern erhalten?

Die Bild-Profilanalyse ist darauf ausgelegt, strukturierte Ergebnisse über den öffentlichen Avatar zu liefern, nicht als Bild-Downloader zu fungieren. Wenn ein Arbeitsablauf tatsächlich Bilder anzeigen muss, prüfen Sie, ob dies für den Zweck erforderlich ist und wie die Dateien gespeichert und gelöscht würden. Viele Arbeitsabläufe für Kontaktdaten müssen nur wissen, ob ein öffentlicher Avatar existiert und um welche Art von Bild es sich handelt, was die Analyse bereits beantwortet.

Wie sollten Entwickler unbestimmte WhatsApp-Prüfungen wiederholen?

Sammeln Sie unbestimmte Nummern in einer Warteschlange für Wiederholungen, anstatt sie sofort in einer Schleife erneut zu senden. Prüfen Sie diese später in einer Einzel- oder Mehrfachabfrage erneut und begrenzen Sie die Anzahl der Versuche pro Nummer, damit ein dauerhafter Fehler nicht unendlich weiterläuft. Behalten Sie nach dem letzten Versuch den Status als unbestimmt bei, anstatt ihn in „Kein Profilbild“ umzuwandeln, da diese Ergebnisse unterschiedliche Bedeutungen haben.

Wie können Teams ein Bild prüfen, das sie bereits besitzen, anstatt eine Telefonnummer?

Verwenden Sie die Bild-Profilanalyse. Sie akzeptiert JPEG-, PNG-, WebP- oder GIF-Dateien und wird über den dokumentierten Endpunkt für Bild-Profile mit einem Multipart-Datei-Upload aufgerufen. Sie beschreibt das Bild selbst und liefert Bildtyp und Erscheinungsmerkmale als algorithmische Schätzungen, ohne dass eine Telefonnummer oder ein Konto involviert ist. Dies eignet sich für Bilder, die ein Kunde direkt hochgeladen hat, wie z. B. ein über ein Formular eingereichtes Profilfoto.

Mehr erfahren

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

• Besuchen Sie die Produktwebsite →