WhatsApp-Metriken

Die Metrics-Seite im Bird-Dashboard zeigt, wie Ihr WhatsApp-Kanal abschneidet: wie viel davon das Gerät des Empfängers erreicht hat, ob sich Ihre Fehlerrate verändert und wie schnell alles verarbeitet wurde. Diese Anleitung geht die Seite durch, erklärt jede Kennzahl und zeigt, wann Sie handeln sollten.

Metriken sind die aggregierte Sicht auf alles, was Ihr Workspace sendet. Für den Lebenszyklus einer einzelnen Nachricht (hat diese Nummer sie erhalten, und wann) siehe das WhatsApp-Log und die Events.

Ihre Metriken lesen

Die Metrics-Seite befindet sich unter WhatsApp → Metrics im Bird-Dashboard; sie ist für Workspace-Mitglieder sichtbar, die sowohl die Leseberechtigung für WhatsApp als auch für Analytics besitzen. Jede Kennzahl folgt der Zeitraumauswahl (letzte 24 Stunden, 7, 30 oder 90 Tage). Neue Events erscheinen erst nach Aggregation und Replikation, daher ist der jüngste Zeitraum vorläufig.

Ausgehende Raten verwenden den Annahmezeitpunkt jeder Nachricht. Eine Zustellbestätigung, die heute für eine gestern angenommene Nachricht eintrifft, zählt zu gestern, zusammen mit dem accepted dieser Nachricht. Jeder Zeitraum folgt also den darin angenommenen Nachrichten, während Bestätigungen eintreffen. Aktuelle Stunden können delivered zu niedrig ausweisen, solange Bestätigungen noch ausstehen. accepted ist der Nenner für die Kacheln zu Zustell- und Fehlerrate.

Zähler repräsentieren eindeutige Nachrichten pro beobachtetem Event und können bei großem Volumen Näherungswerte sein. Sie bilden keinen zwingenden Trichter: Eine Lesebestätigung kann ohne eine Zustellbestätigung vorliegen, und fehlende Beobachtungen können Lücken zwischen den Stufen hinterlassen. Gruppenstatistiken zählen ebenfalls Nachrichten, nicht Empfänger; die erste beobachtete Teilnehmerzustellung kann den Zähler für zugestellt erhöhen, bevor jedes Gruppenmitglied die Nachricht erhalten hat.

Die Zusammenfassungs-Kacheln

Die Kachelzeile oben ist Ihr Schnellcheck:

Delivery rate: zugestellte Nachrichten als Anteil an den angenommenen. Die Kachel zeigt Healthy oberhalb von 95 %. Liegt der Wert auf oder unter dieser Schwelle, erreicht etwas die Geräte nicht: ungültige Nummern, ein abgelaufenes Kundenservice-Fenster oder ein Template-Problem. Das Fehlerursachen-Histogramm (siehe Fehlerrate und ihre Ursachen) verrät, woran es liegt.
Failure rate: der Anteil angenommener Nachrichten, die mit failed endeten. Die Kachel zeigt Ihre Rate gegen ein 5-%-Limit mit Fortschrittsbalken an; wird es erreicht, wechselt die Kachel auf Risk. Eine dauerhaft hohe Fehlerrate deutet in der Regel auf Listenqualität, ein abgelaufenes Kundenservice-Fenster oder ein Meta-Rate-Limit hin.
Accepted: die Rohanzahl der im Zeitraum angenommenen Nachrichten, zusammen mit der an das WhatsApp-Netzwerk weitergegebenen Anzahl (sent).

Die Schwellenwerte von 95 % und 5 % sind die Leitplanken, mit denen wir die Kacheln einfärben. Sie sind bewusst konservativ gewählt; eine Kachel kann Healthy anzeigen und trotzdem Verbesserungspotenzial haben.

Zustellung im Zeitverlauf

Das Zustelldiagramm zeigt accepted, delivered und failed über den Zeitraum, damit Sie Trends und einzelne Ausreißer erkennen: eine fehlerhafte Kampagne, ein falsch importierter Nummernbestand oder ein Template, das abgelehnt wird. Die Intervallgröße folgt dem Zeitraum (stündlich bei 24 Stunden, täglich bei längeren Fenstern).

Fehlerrate und ihre Ursachen

Unterhalb des Zustelldiagramms auf der Metrics-Seite zeichnet eine Fehlerraten-Linie die Fehlerrate pro Intervall über den Zeitraum, während die Zusammenfassungs-Kachel den Wert für das gesamte Fenster enthält. Ein Histogramm schlüsselt Fehler nach normalisiertem Fehlercode auf, sortiert nach Anzahl mit dem jeweiligen Anteil am Fehlervolumen. Die Fehlerursachen von WhatsApp sind eine offene Menge, daher listet das Histogramm die tatsächlich im Zeitraum aufgetretenen Codes statt einer festen Liste; ein steigender Balken bei einem Code führt Sie direkt zur Lösung.

Zustelllatenz

Die Latenztabelle zeigt zwei Stufen bei den Perzentilen p50, p95 und p99:

Processing: von der Annahme einer Nachricht bis zur erfolgreichen Übergabe an den WhatsApp-Provider. Ein langsames Perzentil hier erfordert eine Untersuchung des Sendepfads einschließlich der Provider-Übergabe.
Total: Ende-zu-Ende, von der Annahme der Nachricht bis WhatsApp die Zustellung an das Gerät des Empfängers bestätigt. Die Differenz zwischen Total und Processing ist das WhatsApp-Netzwerk und das Empfängergerät, worauf wir keinen Einfluss haben. Ein Telefon, das eine Stunde offline ist, verlängert Total, während Processing unverändert bleibt.

Nutzen Sie p95/p99, um besonders langsame Zustellungen zu erkennen: ein gesunder Median bei langsamem p99 deutet meist auf ein einzelnes Template oder Ziel hin. Latenz ist ein Gesamtfensterwert; eine Stufe oder ein Perzentil ohne Daten im Zeitraum zeigt einen Platzhalter.

Aufschlüsselungen

Das Breakdowns-Panel unterteilt dieselben Zustellzahlen, damit Sie ein Problem bis zu seiner Quelle eingrenzen können:

By number: akzeptiertes, zugestelltes und fehlgeschlagenes Volumen jeder sendenden Geschäftsnummer mit ihrer Zustellrate, sodass Sie Absender nebeneinander vergleichen können.
By template: dieselbe Aufteilung pro Template, um das eine Template zu finden, das eine Rate herunterzieht.
By template category: dieselbe Aufteilung über Metas Template-Kategorien, die Dimension, die auch Ihre Kosten bestimmt.
By tag: die Tags, die Sie an einen Versand anhängen, die flexibelste Dimension: taggen Sie eine Kampagne, ein Template oder eine Experimentvariante und vergleichen Sie sie direkt.
By country: dieselbe Aufteilung pro Zielland, um zu sehen, ob ein Zustellproblem an einem Markt liegt und nicht an einem Absender oder Template. Ein Empfänger, dessen Land nicht ermittelt werden kann (eine Nummer, die wie eine Telefonnummer aussieht, aber keinem Land zugeordnet ist, oder ein internationaler Bereich wie Freephone), wird unter ZZ gezählt, derselbe Platzhalter, den die Länderaufschlüsselung von SMS verwendet. Gruppenversendungen sind ausgenommen, weil eine Gruppe mehrere Länder umfassen kann und kein einzelnes Zielland hat. Die historische Länderabdeckung vor Einführung dieser Aufschlüsselung kann unvollständig sein, einschließlich zugestellter oder gelesener Beobachtungen ohne passende Accepted-Zähler. Die aggregierte Historie überdauert das 30-Tage-Fenster für Nachrichtendetails; 30 Tage abzuwarten repariert diese älteren Kohorten nicht.

Jede Zeile erhält außerdem einen abgeleiteten Status (Healthy, Watching oder Throttled), der auf ihren eigenen Zustell- und Fehlerraten basiert, sodass eine problematische Nummer oder Kategorie auffällt, ohne dass Sie jede Spalte lesen müssen. Jeder Tab sortiert die Top-Zeilen für den Zeitraum; wenn eine Dimension mehr unterschiedliche Werte hat als darstellbar, zeigt das Panel "Top N of M" an.

Die untere Hälfte der WhatsApp-Metriken-Seite im Bird-Dashboard: die Zustelllatenz-Tabelle (Processing p50/p95/p99) über dem Breakdowns-Panel mit Zustellung aufgeschlüsselt nach Nummer, Template, Template-Kategorie und Tag

Programmatischer Zugriff

Die Aggregate hinter dieser Seite sind auch eine öffentliche API. Typisierte Methoden sind in den TypeScript-, Python-, PHP- und Go-SDKs unter bird.whatsapp.stats verfügbar, die bird CLI stellt sie als bird whatsapp stats <verb> bereit, und ein Agent erreicht sie über die whatsapp_stats_* MCP-Tools. Vollständige Request- und Response-Schemas finden Sie in der API-Referenz.

Das Aggregat und die Zeitreihe

GET /v1/whatsapp/stats/summary gibt eine Aggregatzeile für das Fenster zurück: Lebenszyklus-Zähler (accepted, sent, delivered, failed, rejected) mit Zustell- und Fehlerraten, Engagement (read, read_rate) und Latenzperzentile (p50, p95, p99) für drei Stufen: Processing, Delivery und Total. /daily und /hourly geben dieselben Lebenszyklus- und Lesezähler mit einer Zeile pro Kalendertag oder Stunde zurück, jeweils mit eigenen Latenzperzentilen; nur die Raten (delivery_rate, failure_rate, read_rate) sind Gesamtfensterwerte; lesen Sie diese aus /summary. Alle drei akzeptieren jeweils einen Dimensionsfilter: template, category, tag oder phone_number. Hier schränkt phone_number auf einen einzelnen geschäftlichen Absender im E.164-Format ein, nicht auf den Kontakt, nach dem der veraltete phone_number-Parameter von GET /v1/whatsapp/messages filtert.

Die Leserate ist read / delivered, während Zustell- und Fehlerraten accepted verwenden. Ein Nenner von null gibt null zurück, d. h. die Rate kann nicht berechnet werden. Die Leserate ist nicht auf 100 % begrenzt, sodass fehlende Zustellbeobachtungen einen höheren Wert ergeben können; das ist eine zu untersuchende Beobachtungslücke, kein Beleg dafür, dass mehr als jeder Empfänger die Nachricht gelesen hat.

Latenzperzentile verwenden aufgezeichnete Stichproben. Ein fehlender Zustelllatenz-Wert bedeutet nicht Latenz null, und die Gesamtlatenz kann vorhanden sein, wenn der zwischenzeitliche Sent-Zeitstempel nicht verfügbar war. Mitteln Sie keine finalisierten Perzentile aus verschiedenen Intervallen. Wiederholte Events können Latenzverteilungen beeinflussen, auch wenn die Zähler für eindeutige Nachrichten dedupliziert bleiben.

Wenn vorhanden, gibt data_as_of die Aggregationsaktualität an. Das beweist nicht, dass alle Provider-Callbacks eingetroffen sind oder dass die Abrechnung abgeschlossen ist. Ein null-Wert für die Aktualität bedeutet, dass er für diese Antwort nicht verfügbar war.

Fenster wählen

from und to akzeptieren einen Kalendertag oder einen RFC-3339-Zeitstempel, aber welche Form ein Endpunkt akzeptiert, unterscheidet sich:

Endpunkt	Grenzen	Maximales Fenster
/summary	Beide Kalendertage oder beide RFC-3339-Zeitstempel	365 Tage oder 720 Stunden bei Zeitstempeln
/daily	Nur Kalendertage	365 Tage
/hourly	Nur RFC-3339-Zeitstempel	720 Stunden (30 Tage)

Bei /summary gibt die Kombination einer Tagesgrenze mit einer Zeitstempelgrenze 422 zurück. Zeitstempelgrenzen werden auf /summary und /hourly auf die volle Stunde abgerundet, den einzigen beiden Endpunkten, die sie akzeptieren. Setzen Sie timezone auf einen IANA-Bezeichner, um Tages- und Stundengrenzen lokal statt in UTC zu berechnen; sobald er gesetzt ist, wird ein numerischer UTC-Offset wie +05:45 in einer Zeitstempelgrenze abgelehnt. Fügen Sie compare=previous_period zu /summary hinzu, um das vorangehende gleich lange Fenster und die Veränderung dazu zu erhalten.

Aufschlüsselungen

Sechs Endpunkte sortieren dieselben Zustellzahlen nach einer Dimension, jeder bereits eindimensional, sodass keiner einen Filter akzeptiert: nach Nummer, nach Template, nach Template-Kategorie, nach Tag und nach Fehlercode (nur fehlgeschlagene Nachrichten, gruppiert nach normalisierter Fehlerursache). Zeilen sind nach akzeptiertem Volumen (Fehleranzahl bei Fehlercodes) sortiert und begrenzt auf limit (Standard 50, Maximum 200). Ein Versand ohne Wert für eine Dimension fehlt in dieser Aufschlüsselung: Ein Freitext-Versand löst kein Template auf, und ein nicht getaggter Versand keinen Tag. Eine Nachricht mit mehreren Tags kann in mehreren Tag-Zeilen erscheinen, daher ergibt die Addition dieser Zeilen nicht das eindeutige Workspace-Volumen. Vergleichen Sie eine Aufschlüsselung im Zeitverlauf mit sich selbst. Jede Zeile außer Fehlercode-Zeilen enthält auch eigene latency-Perzentile. Eine sechste, nach Land, gruppiert dieselben Zahlen nach dem Zielmarkt des Empfängers; ein Empfänger, dessen Land nicht aufgelöst werden kann, wird unter ZZ gezählt, und Gruppenversendungen fehlen, weil ein Versand mehrere Länder umfassen kann.

Empfangene Nachrichten

Vier Endpunkte unter /v1/whatsapp/stats/inbound/ decken ab, was Ihre Nummern empfangen statt gesendet haben: Zusammenfassung, täglich, stündlich und nach Telefonnummer. Jede Zeile enthält nur einen received-Zähler und folgt dem Eintrittszeitpunkt der eingehenden Nachricht. Eine empfangene Nachricht hat keinen ausgehenden Zustelllebenszyklus zur weiteren Aufschlüsselung. Diese sind unter bird.whatsapp.stats.inbound in den SDKs und bird whatsapp stats inbound <verb> in der CLI verschachtelt.

Abgleich pro Nachricht

Die Stats-Endpunkte beantworten Aggregatfragen; sie ersetzen nicht die Abfrage einzelner Nachrichten. Um zu bestätigen, was mit einer Nachricht passiert ist, konsumieren Sie Webhook-Events in Echtzeit oder blättern Sie durch GET /v1/whatsapp/messages und den Events-Endpunkt jeder Nachricht, dessen Filter (Status, Empfänger, Tag, Zeitfenster) die meisten Abgleichaufgaben abdecken.

Nächste Schritte

WhatsApp-Analytics: Nachrichtenbeobachtungen mit bestätigten Kundenergebnissen verknüpfen
WhatsApp-Log: die Einzelnachricht-Ansicht hinter den aggregierten Zahlen
Events: der Lebenszyklus-Stream pro Nachricht, aus dem die Metriken abgeleitet werden
WhatsApp-Nachrichten senden: Kategorien, Tags und das Kostenmodell pro Nachricht

Verwandte Ressourcen