SMS stats API
Każda wartość w panelu Metrics pochodzi z SMS stats API. Używaj tych samych agregatów w dashboardzie, hurtowni danych lub health checku. Endpointy tylko do odczytu, ograniczone do obszaru roboczego, wymagają klucza API z dostępem do odczytu w zakresie sms. Odpowiedź jest zgodna z panelem dla tego samego zakresu i filtrów.
Typowane metody są dostępne w SDK TypeScript, Python, PHP i Go pod sms.stats, bird CLI udostępnia je jako bird sms stats, a agent korzysta z nich przez sms_stats_* narzędzia MCP. Pełne schematy żądań i odpowiedzi znajdziesz w dokumentacji API.
Agregat i seria czasowa
Trzy endpointy obsługują górną część panelu:
- GET /v1/sms/stats/summary zwraca jeden wiersz agregatu dla całego okna: liczniki cyklu życia (accepted, sent, delivered, undelivered, failed, rejected, expired), pochodne delivery_rate i failure_rate oraz percentyle opóźnień przetwarzania, dostarczenia i całkowite (p50, p95, p99). Przekaż compare=previous_period, a odpowiedź uwzględni też poprzednie okno o tej samej długości i zmianę względem niego.
- GET /v1/sms/stats/daily i GET /v1/sms/stats/hourly zwracają liczniki cyklu życia, jeden wiersz na dzień lub na godzinę. Wskaźniki i opóźnienia dotyczą całego okna, więc odczytuj je z /summary, a nie z poszczególnych przedziałów.
Każdy wskaźnik jest zwracany jako ułamek dziesiętny, więc delivery_rate równy 0.9739 oznacza 97,39%. Wskaźnik, którego mianownik wynosi zero, ma wartość null, co pozwala okresowi bez zaakceptowanych wiadomości raportować delivery_rate zamiast 0. Wartości odnoszą się do czasu wysłania wiadomości. Potwierdzenie dostarczenia otrzymane dziś dla wiadomości zaakceptowanej wczoraj jest liczone na poczet wczoraj. Ostatnie okno zaniża więc delivered, dopóki raporty dostarczeń wciąż napływają, dlatego traktuj ostatnie kilka godzin jako dane tymczasowe, nie ostateczne.
Liczniki używają przybliżonej agregacji unikalnych wiadomości. Wiadomość może pojawić się w więcej niż jednym statusie cyklu życia w miarę postępu, więc liczniki statusów nie wykluczają się wzajemnie i nie wolno ich sumować jako łącznej liczby wiadomości. Jako mianownika wskaźnika wychodzącego używaj zaakceptowanych wiadomości. Te agregaty operacyjne nie są rejestrem rozliczeniowym; do uzgodnień używaj rekordów wiadomości i rozliczeń.
Wybór okna
from i to przyjmują dzień kalendarzowy (YYYY-MM-DD) lub znacznik czasu RFC 3339, a akceptowane formaty różnią się w zależności od endpointu:
| Endpoint | Granice | Maksymalne okno |
|---|---|---|
| /summary | Oba dni lub oba znaczniki czasu | 365 dni lub 720 godzin dla znaczników czasu |
| /daily | Dni kalendarzowe | 365 dni |
| /hourly | Znaczniki czasu RFC 3339 | 720 godzin (30 dni) |
Granice w znacznikach czasu mają granulację godzinową, dzięki czemu ruchome okno 24-godzinne to jedno żądanie. W /summary mieszanie dnia ze znacznikiem czasu zwraca 422.
Ustaw timezone na identyfikator IANA, np. America/New_York, aby obliczać granice i pomijane wartości domyślne w tej strefie zamiast UTC. Gdy timezone jest ustawione, Bird odrzuca numeryczne przesunięcia UTC, takie jak +05:45, w granicach znaczników czasu. Używaj zamiast tego znaczników czasu Z lub dni kalendarzowych.
Rozbicia
Siedem endpointów dzieli te same liczby dostarczeń według jednego wymiaru:
- Dokąd trafiła: /countries (kraj docelowy) i /carriers (operator, który ją obsłużył).
- Co wysłałeś: /originators (adres nadawcy, z którego wyszła), /categories i /tags.
- Jak się zakończyła: /statuses (jeden wiersz na status cyklu życia z aktywnością) i /error-codes.
Wszystkie znajdują się pod /v1/sms/stats/. Wiersze krajów, operatorów, nadawców, kategorii, tagów i kodów błędów są rankingowane według sort i ograniczone przez limit (domyślnie 50, maksymalnie 200). Odpowiedzi zawierają total, czyli liczbę unikalnych wartości w oknie, dzięki czemu wykryjesz obcięty wynik. Wiersze, których metryka sortowania jest wskaźnikiem z mianownikiem równym zero, pojawiają się na końcu. Rozbicie statusów ma co najwyżej siedem wierszy i nie ma parametrów sort ani limit.
Sześć rankingowanych rozbić może też zwrócić krótką serię dla każdego wiersza. Ustaw include_trend=true i wybierz trend_grain=daily lub hourly. Trendy wymagają limit równego 50 lub mniej oraz okna co najwyżej 90 dni dla przedziałów dziennych lub 720 godzin dla przedziałów godzinowych.
sort domyślnie przyjmuje accepted w rozbiciach wolumenowych i failed w /error-codes. Endpoint /error-codes grupuje według znormalizowanej przyczyny błędu Bird, a nie surowego kodu operatora. Jego wartość współpracuje też z filtrem error_code w GET /v1/sms/messages, wiążąc wiersz z jego wiadomościami.
/tags liczy tylko otagowane wiadomości, a wiadomość z kilkoma tagami jest liczona raz pod każdym z nich. Wiersze nie sumują się więc do łącznej wartości za okres. Uzgadniaj jeden wynik /tags z drugim zamiast używać /summary.
/statuses zwraca status i liczbę zamiast pełnego bloku dostarczenia. Każdy wiersz liczy wiadomości zaobserwowane w danym statusie cyklu życia; wiadomość może pojawić się w kilku wierszach.
Odebrane wiadomości
Sześć kolejnych endpointów pod /v1/sms/stats/inbound/ liczy to, co Twoje numery odebrały, a nie to, co wysłałeś: /summary, /daily i /hourly dla sum i serii oraz /countries, /operators i /numbers dla rozbić. Przyjmują te same parametry okna i strefy czasowej co ich odpowiedniki wychodzące.
Dwie rzeczy różnią się od rodziny wychodzącej. Każdy wiersz zawiera zwykły licznik received bez bloku dostarczenia i wskaźników, ponieważ wiadomość przychodząca nie ma cyklu życia dostarczenia do agregowania. Endpoint /operators wyklucza wiadomości, których operatora nadawczego nie zgłosił operator obsługujący wiadomość, więc jego wiersze mogą sumować się do mniej niż /inbound/summary za ten sam okres. Używaj podsumowania jako łącznej wartości obszaru roboczego; wiersze operatorów obejmują tylko wiadomości ze zgłoszonym operatorem.
Następne kroki
Analityka SMS łączy te raporty z przeglądem kampanii i badaniem dostarczeń.
- Metrics: sprawdź panel, który te wartości renderują.
- Log SMS: sprawdź wiadomości stojące za agregatami.
- Events: konsumuj strumień zdarzeń stojący za agregatami.
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.
Zrozum koncepcjęWhat does a delivery receipt tell you?Podążaj ścieżką naukiOperate messaging reliably
Uzyskaj brief wdrożeniowy