Metryki WhatsApp
Strona Metrics w panelu Bird pokazuje, jak radzi sobie Twój kanał WhatsApp: ile wiadomości dotarło do urządzenia odbiorcy, czy wskaźnik niepowodzeń rośnie i jak szybko wszystko przebiegało. Ten przewodnik omawia tę stronę, znaczenie poszczególnych liczb i sytuacje, w których warto podjąć działanie.
Metryki to widok zagregowany dla wszystkiego, co wysyła Twój obszar roboczy. Aby prześledzić cykl życia pojedynczej wiadomości (czy ten numer ją otrzymał i kiedy), zobacz log WhatsApp i zdarzenia.
Odczytywanie metryk
Strona Metrics znajduje się pod WhatsApp → Metrics w panelu Bird; widzą ją członkowie obszaru roboczego z uprawnieniami WhatsApp read i Analytics read. Każda liczba uwzględnia wybrany zakres (ostatnie 24 godziny, 7, 30 lub 90 dni). Nowe zdarzenia pojawiają się po agregacji i replikacji, więc dane za najnowszy okres są wstępne.
Wskaźniki wychodzące opierają się na czasie akceptacji wiadomości. Potwierdzenie dostarczenia, które przychodzi dziś dla wiadomości zaakceptowanej wczoraj, jest liczone do wczorajszego dnia, razem z accepted tej wiadomości. Każdy zakres śledzi więc wiadomości zaakceptowane w jego ramach w miarę napływania obserwacji. Ostatnie godziny mogą zaniżać delivered, dopóki potwierdzenia wciąż napływają. accepted jest mianownikiem dla kart wskaźnika dostarczenia i niepowodzeń.
Liczniki reprezentują odrębne wiadomości dla każdego zaobserwowanego zdarzenia i mogą być przybliżone przy dużej skali. Nie tworzą obowiązkowego lejka: potwierdzenie odczytania może istnieć bez potwierdzenia dostarczenia, a brakujące obserwacje mogą powodować luki między etapami. Statystyki grupowe również liczą wiadomości, nie odbiorców; pierwsze zaobserwowane dostarczenie do uczestnika może zwiększyć licznik dostarczeń, zanim każdy członek grupy otrzyma wiadomość.
Kafelki podsumowania
Rząd kafelków u góry to szybki przegląd kondycji:
- Delivery rate: udział dostarczonych wiadomości w zaakceptowanych. Kafelek pokazuje Healthy powyżej 95%. Na tym poziomie lub poniżej coś nie dociera do urządzeń: nieprawidłowe numery, wygasłe okno obsługi klienta lub problem z szablonem. Histogram przyczyn niepowodzeń (zobacz Failure rate and its causes) wskazuje, która to przyczyna.
- Failure rate: udział zaakceptowanych wiadomości, które zakończyły się statusem failed. Kafelek porównuje Twój wskaźnik z limitem 5% na pasku postępu; po jego osiągnięciu kafelek zmienia się na Risk. Utrzymujący się wysoki wskaźnik niepowodzeń zwykle wskazuje na jakość listy, wygasłe okno obsługi klienta lub limit częstotliwości Meta.
- Accepted: łączna liczba wiadomości zaakceptowanych w zakresie, z liczbą przekazanych do sieci WhatsApp (sent).
Progi 95% i 5% to wartości graniczne, według których kolorujemy kafelki. Są celowo konserwatywne; kafelek może pokazywać Healthy i nadal mieć pole do poprawy.
Dostarczenia w czasie
Wykres dostarczeń przedstawia liczbę wiadomości accepted, delivered i failed w zakresie, dzięki czemu zauważysz trendy i jednorazowe skoki: nieudaną kampanię, błędny import listy numerów czy szablon, który zaczął być odrzucany. Rozmiar przedziału zależy od zakresu (godzinowy dla 24 godzin, dzienny dla dłuższych okien).
Wskaźnik niepowodzeń i jego przyczyny
Pod wykresem dostarczeń na stronie Metrics linia wskaźnika niepowodzeń rysuje wartość dla każdego przedziału w zakresie, a kafelek Failure rate summary zawiera wartość dla całego okna. Histogram rozkłada niepowodzenia według znormalizowanego kodu błędu, uszeregowanego według liczby z udziałem każdego kodu w niepowodzeniach. Przyczyny niepowodzeń WhatsApp stanowią otwarty zbiór, więc histogram wyświetla kody, które faktycznie wystąpiły w zakresie, a nie stałą listę; rosnący słupek przy jednym kodzie od razu wskazuje rozwiązanie.
Opóźnienie dostarczenia
Tabela opóźnień prezentuje dwa etapy w percentylach p50, p95 i p99:
- Processing: od zaakceptowania wiadomości do pomyślnego przekazania do dostawcy WhatsApp. Wolny percentyl na tym etapie wymaga zbadania ścieżki wysyłki, w tym przekazania do dostawcy.
- Total: od początku do końca, od zaakceptowania wiadomości do potwierdzenia dostarczenia na urządzenie odbiorcy przez WhatsApp. Różnica między Total a Processing to sieć WhatsApp i urządzenie odbiorcy, na które nie mamy wpływu. Telefon offline przez godzinę wydłuża Total, nie zmieniając Processing.
Używaj p95/p99, aby wyłapać wolny ogon: zdrowa mediana przy wolnym p99 zwykle wskazuje na jeden szablon lub kierunek z opóźnieniem. Opóźnienie jest wartością dla całego okna; etap lub percentyl bez danych dla zakresu wyświetla placeholder.
Podziały
Panel Breakdowns dzieli te same liczby dostarczeń, abyś mógł przypisać problem do źródła:
- By number: liczba zaakceptowanych, dostarczonych i nieudanych wiadomości dla każdego numeru firmowego ze wskaźnikiem dostarczenia, aby porównać nadawców obok siebie.
- By template: ten sam podział na szablon, aby znaleźć szablon obniżający wskaźnik.
- By template category: ten sam podział według kategorii szablonów Meta, czyli kategorii, która wpływa też na koszty.
- By tag: tagi, które dołączasz do wysyłki, najbardziej elastyczny podział: otaguj kampanię, szablon lub wariant eksperymentu i porównaj je bezpośrednio.
- By country: ten sam podział według kraju docelowego, aby sprawdzić, czy problem z dostarczeniem dotyczy rynku, a nie nadawcy czy szablonu. Odbiorca, którego kraju nie da się ustalić (numer wyglądający jak numer telefonu, ale nieprzypisany do żadnego kraju, lub zakres międzynarodowy, np. freephone), jest liczony w ZZ, tym samym placeholderze, którego używa podział SMS według kraju. Wysyłki grupowe są pomijane, ponieważ grupa może obejmować kilka krajów i nie ma jednego kierunku docelowego. Historyczne pokrycie krajowe sprzed uruchomienia tego podziału może być niekompletne, w tym obserwacje dostarczenia lub odczytania bez odpowiadających im zaakceptowanych wiadomości. Historia zagregowana wykracza poza 30-dniowe okno szczegółów wiadomości; odczekanie 30 dni nie naprawia tych starszych kohort.
Każdy wiersz otrzymuje też pochodny status (Healthy, Watching lub Throttled) wynikający z jego własnych wskaźników dostarczenia i niepowodzeń, więc numer lub kategoria z problemami wyróżniają się bez czytania każdej kolumny. Każda zakładka rankuje najwyższe wiersze dla zakresu; gdy wymiar ma więcej odrębnych wartości niż się mieści, panel wyświetla "Top N of M".
Dostęp programistyczny
Agregaty stojące za tą stroną są też publicznym API. Typowane metody są dostępne w SDK TypeScript, Python, PHP i Go pod bird.whatsapp.stats, bird CLI udostępnia je jako bird whatsapp stats <verb>, a agent korzysta z nich przez whatsapp_stats_* narzędzia MCP. Pełne schematy żądań i odpowiedzi znajdziesz w dokumentacji API.
Agregat i seria czasowa
GET /v1/whatsapp/stats/summary zwraca jeden zagregowany wiersz dla okna: liczniki cyklu życia (accepted, sent, delivered, failed, rejected) ze wskaźnikami dostarczenia i niepowodzeń, zaangażowanie (read, read_rate) oraz percentyle opóźnień (p50, p95, p99) dla trzech etapów: processing, delivery i total. /daily i /hourly zwracają te same liczniki cyklu życia i odczytań po jednym wierszu na dzień lub godzinę kalendarzową, każdy z własnymi percentylami opóźnień; jedynie wskaźniki (delivery_rate, failure_rate, read_rate) dotyczą całego okna, odczytuj je z /summary. Wszystkie trzy przyjmują jednocześnie jeden filtr wymiarowy: template, category, tag lub phone_number. Tutaj phone_number ogranicza wyniki do pojedynczego nadawcy firmowego w formacie E.164, a nie kontaktu, według którego filtruje przestarzały parametr phone_number endpointu GET /v1/whatsapp/messages.
Wskaźnik odczytań to read / delivered, natomiast wskaźniki dostarczenia i niepowodzeń używają accepted. Zerowy mianownik zwraca null, co oznacza, że wskaźnika nie da się obliczyć. Wskaźnik odczytań nie jest ograniczony do 100%, więc brakujące obserwacje dostarczeń mogą dać wyższą wartość; to luka w obserwacjach do zbadania, nie dowód, że więcej niż każdy odbiorca przeczytał wiadomość.
Percentyle opóźnień korzystają z zarejestrowanych próbek. Brak próbki opóźnienia dostarczenia nie oznacza zerowego opóźnienia, a opóźnienie całkowite może być dostępne, gdy pośredni znacznik czasu wysłania był niedostępny. Nie uśredniaj sfinalizowanych percentyli z osobnych przedziałów. Powtórzone zdarzenia mogą wpływać na rozkłady opóźnień, nawet gdy liczniki odrębnych wiadomości pozostają zdeduplikowane.
Jeśli jest obecne, data_as_of raportuje świeżość agregacji. Nie dowodzi to, że wszystkie callbacki od dostawców dotarły ani że rozliczenia zostały zamknięte. Wartość null oznacza, że świeżość była niedostępna dla danej odpowiedzi.
Wybór okna
from i to przyjmują dzień kalendarzowy lub znacznik czasu RFC 3339, ale akceptowane formy różnią się w zależności od endpointu:
| Endpoint | Granice | Maksymalne okno |
|---|---|---|
| /summary | Oba dni kalendarzowe lub oba znaczniki RFC 3339 | 365 dni lub 720 godzin dla znaczników |
| /daily | Tylko dni kalendarzowe | 365 dni |
| /hourly | Tylko znaczniki RFC 3339 | 720 godzin (30 dni) |
W /summary mieszanie granicy dziennej z granicą jako znacznik czasu zwraca 422. Granice jako znaczniki są zaokrąglane w dół do godziny w /summary i /hourly, jedynych dwóch endpointach, które je przyjmują. Ustaw timezone na identyfikator IANA, aby obliczać granice dni i godzin lokalnie zamiast w UTC; po jego ustawieniu numeryczny offset UTC, np. +05:45 w znaczniku czasu, jest odrzucany. Dodaj compare=previous_period do /summary, aby uzyskać poprzednie okno o równej długości i zmianę względem niego.
Podziały
Sześć endpointów rankuje te same liczby dostarczeń według jednego wymiaru; każdy jest już jednowymiarowy, więc żaden nie przyjmuje filtra: według numeru, według szablonu, według kategorii szablonu, według tagu i według kodu błędu (tylko nieudane wiadomości, pogrupowane według znormalizowanej przyczyny niepowodzenia). Wiersze są rankowane według liczby zaakceptowanych wiadomości (liczby niepowodzeń dla kodów błędów) i ograniczone do limit (domyślnie 50, maksymalnie 200). Wysyłka bez wartości dla danego wymiaru nie pojawia się w tym podziale: wiadomość o swobodnej treści nie ma szablonu, a wiadomość bez tagu nie ma przypisanego tagu. Wiadomość z kilkoma tagami może pojawić się w kilku wierszach tagów, więc sumowanie tych wierszy nie daje unikalnej liczby wiadomości obszaru roboczego. Porównuj podział z samym sobą w czasie. Każdy wiersz oprócz wiersza kodu błędu zawiera też własne percentyle latency. Szósty, według kraju, grupuje te same liczby według rynku docelowego odbiorcy; odbiorca, którego kraju nie da się ustalić, jest liczony w ZZ, a wysyłki grupowe są pomijane, ponieważ jedna wysyłka może obejmować kilka krajów.
Odebrane wiadomości
Cztery endpointy pod /v1/whatsapp/stats/inbound/ dotyczą wiadomości odebranych przez Twoje numery, a nie wysłanych: podsumowanie, dziennie, godzinowo i według numeru telefonu. Każdy wiersz zawiera tylko licznik received i odnosi się do czasu wystąpienia wiadomości przychodzącej. Odebrana wiadomość nie ma wychodzącego cyklu życia dostarczenia do dalszego podziału. W SDK są one zagnieżdżone pod bird.whatsapp.stats.inbound, a w CLI pod bird whatsapp stats inbound <verb>.
Uzgadnianie na poziomie wiadomości
Endpointy statystyk odpowiadają na pytania zagregowane; nie zastępują sprawdzania poszczególnych wiadomości. Aby potwierdzić, co stało się z jedną wiadomością, konsumuj zdarzenia webhook na bieżąco lub przeglądaj GET /v1/whatsapp/messages i endpoint zdarzeń każdej wiadomości, którego filtry (status, odbiorca, tag, okno czasowe) pokrywają większość zadań uzgadniania.
Następne kroki
- Analityka WhatsApp: powiąż obserwacje wiadomości z potwierdzonymi rezultatami po stronie klienta
- Log WhatsApp: widok poszczególnych wiadomości stojący za zagregowanymi liczbami
- Zdarzenia: strumień cyklu życia wiadomości, z którego metryki są wyprowadzane
- Wysyłanie wiadomości WhatsApp: kategorie, tagi i model kosztu na wiadomość
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.
Obejrzyj przewodnikConnecting WhatsApp to Bird: from buying a number to a live channelZrozum koncepcjęWhat is the 24-hour customer service window on WhatsApp?Użyj narzędziaWhatsApp message builderPoznaj możliwościWhatsApp
Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy