SMS stats API
Setiap nilai di dasbor Metrics berasal dari SMS stats API. Gunakan agregat yang sama di dasbor, data warehouse, atau health check. Endpoint read-only yang tercakup dalam workspace memerlukan kunci API dengan akses baca ke scope sms. Respons cocok dengan dasbor untuk rentang dan filter yang sama.
Metode bertipe tersedia di SDK TypeScript, Python, PHP, dan Go di bawah sms.stats, bird CLI mengeksposnya sebagai bird sms stats, dan agen mengaksesnya melalui sms_stats_* MCP tools. Skema request dan response lengkap ada di referensi API.
Agregat dan deret waktu
Tiga endpoint mencakup bagian atas dasbor:
- GET /v1/sms/stats/summary mengembalikan satu baris agregat untuk seluruh jendela waktu: jumlah lifecycle (accepted, sent, delivered, undelivered, failed, rejected, expired), delivery_rate dan failure_rate turunannya, serta persentil latensi pemrosesan, pengiriman, dan total (p50, p95, p99). Berikan compare=previous_period dan respons juga menyertakan jendela waktu sebelumnya dengan panjang yang sama beserta perubahannya.
- GET /v1/sms/stats/daily dan GET /v1/sms/stats/hourly mengembalikan jumlah lifecycle satu baris per hari atau per jam. Rasio dan latensi adalah angka seluruh jendela, jadi baca dari /summary alih-alih per bucket.
Setiap rasio dikembalikan sebagai angka desimal, jadi delivery_rate sebesar 0.9739 berarti 97,39%. Rasio yang penyebutnya nol bernilai null, sehingga periode tanpa pesan yang diterima API melaporkan delivery_rate alih-alih menampilkan 0. Angka menggunakan waktu kirim pesan. Pesan yang dikonfirmasi sudah sampai hari ini tetapi diterima API kemarin dicatat pada hari kemarin. Jendela waktu terkini oleh karena itu melaporkan delivered lebih rendah selama laporan pengirimannya masih berdatangan, jadi perlakukan beberapa jam terakhir sebagai sementara, bukan final.
Jumlah menggunakan agregasi pesan unik yang bersifat perkiraan. Satu pesan dapat berkontribusi ke lebih dari satu status lifecycle seiring prosesnya berjalan, sehingga jumlah per status tidak saling eksklusif dan tidak boleh dijumlahkan sebagai total pesan. Gunakan pesan accepted sebagai penyebut rasio pengiriman keluar. Agregat operasional ini bukan buku besar tagihan; gunakan catatan pesan dan tagihan untuk rekonsiliasi.
Memilih jendela waktu
from dan to menerima hari kalender (YYYY-MM-DD) atau instant RFC 3339, dan format yang diterima setiap endpoint berbeda:
| Endpoint | Batas | Jendela maksimum |
|---|---|---|
| /summary | Keduanya hari, atau keduanya instant | 365 hari, atau 720 jam untuk instant |
| /daily | Hari kalender | 365 hari |
| /hourly | Instant RFC 3339 | 720 jam (30 hari) |
Batas instant berpresisi jam, yang membuat jendela bergulir 24 jam hanya memerlukan satu request. Di /summary, mencampur hari dengan instant menghasilkan 422.
Atur timezone ke identifier IANA seperti America/New_York untuk menghitung batas dan default yang dihilangkan di zona tersebut alih-alih UTC. Ketika timezone diatur, Bird menolak offset UTC numerik seperti +05:45 pada batas instant. Gunakan instant Z atau hari kalender sebagai gantinya.
Breakdown
Tujuh endpoint memecah angka pengiriman yang sama berdasarkan satu dimensi:
- Ke mana tujuannya: /countries (negara tujuan) dan /carriers (operator yang menanganinya).
- Apa yang Anda kirim: /originators (alamat pengirim yang digunakan), /categories, dan /tags.
- Bagaimana hasilnya: /statuses (satu baris per status lifecycle yang memiliki aktivitas) dan /error-codes.
Semuanya berada di bawah /v1/sms/stats/. Baris country, carrier, originator, category, tag, dan error-code diurutkan berdasarkan sort dan dibatasi oleh limit (default 50, maksimum 200). Responsnya menyertakan total, jumlah nilai unik dalam jendela waktu, sehingga Anda dapat mendeteksi hasil yang terpotong. Baris yang metrik pengurutannya berupa rasio dengan penyebut nol muncul terakhir. Breakdown status memiliki paling banyak tujuh baris dan tidak memiliki parameter sort atau limit.
Enam breakdown berperingkat juga dapat mengembalikan deret pendek per baris. Atur include_trend=true dan pilih trend_grain=daily atau hourly. Tren memerlukan limit sebesar 50 atau kurang dan jendela paling lama 90 hari untuk bucket harian atau 720 jam untuk bucket per jam.
sort default-nya accepted pada breakdown volume dan failed pada /error-codes. Endpoint /error-codes mengelompokkan berdasarkan alasan kegagalan yang dinormalisasi dari Bird alih-alih kode operator mentah. Nilainya juga berfungsi dengan filter error_code di GET /v1/sms/messages, menghubungkan baris ke pesannya.
/tags hanya menghitung pesan bertag, dan pesan dengan beberapa tag dihitung sekali di bawah masing-masing tag. Barisnya oleh karena itu tidak berjumlah sama dengan total periode. Rekonsiliasi satu hasil /tags dengan yang lain alih-alih menggunakan /summary.
/statuses mengembalikan status dan jumlah, bukan blok pengiriman lengkap. Setiap baris menghitung pesan yang teramati dalam status lifecycle tersebut; satu pesan dapat muncul di beberapa baris.
Pesan masuk
Enam endpoint lagi di bawah /v1/sms/stats/inbound/ menghitung apa yang diterima nomor Anda, bukan apa yang Anda kirim: /summary, /daily dan /hourly untuk total dan deret, serta /countries, /operators dan /numbers untuk breakdown. Endpoint ini menerima parameter jendela waktu dan zona waktu yang sama dengan padanan pengiriman keluarnya.
Dua hal berbeda dari keluarga pengiriman keluar. Setiap baris memuat jumlah received biasa, tanpa blok pengiriman atau rasio, karena pesan masuk tidak memiliki lifecycle pengiriman untuk diagregasi. Endpoint /operators mengecualikan pesan yang operator pengirimnya tidak dilaporkan oleh carrier, sehingga barisnya dapat berjumlah kurang dari /inbound/summary untuk periode yang sama. Gunakan summary sebagai total workspace; baris operator hanya mencakup pesan dengan operator yang dilaporkan.
Langkah selanjutnya
Analitik SMS menghubungkan pelaporan ini ke tinjauan kampanye dan investigasi pengiriman.
- Metrics: periksa dasbor tempat nilai-nilai ini dirender.
- Log SMS: periksa pesan di balik agregat.
- Events: konsumsi event stream di balik agregat.
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.
Pahami konsepnyaWhat does a delivery receipt tell you?Ikuti jalur pembelajaranOperate messaging reliably
Dapatkan ringkasan implementasi