Event SMS

Setiap pesan melewati siklus hidup, dan Bird mengirimkan event di setiap langkahnya. Halaman ini adalah kosakata event lengkap; cara event dikirim ke endpoint Anda (tanda tangan, percobaan ulang, replay) dibahas di Panduan Webhooks.

Siklus hidup pengiriman, sebagai jalur melalui tipe-tipe event:

sms.accepted: Bird menerima pesan dan sedang mempersiapkan penyerahan ke operator.
sms.sent: Bird telah menyerahkan pesan ke operator dan menunggu tanda terima pengiriman.
Satu event terminal:
- sms.delivered: Operator mengonfirmasi pengiriman ke perangkat.
- sms.undelivered: Operator melaporkan kegagalan pengiriman sementara, misalnya perangkat tidak tersedia.
- sms.failed: Kegagalan permanen menghentikan pengiriman.
- sms.expired: Operator berhenti mencoba dan melaporkan pesan sebagai kedaluwarsa.

Event terminal memunculkan tanda terima pengiriman dari operator, yang oleh platform SMS disebut laporan pengiriman atau DLR.

Pengecualiannya adalah sms.rejected: pesan ditolak (oleh pemeriksaan kebijakan, tagihan yang tidak bisa diselesaikan, atau operator yang menolaknya) alih-alih dicoba dan hilang. Pesan yang ditolak selama pemrosesan hanya memiliki sms.rejected sebagai satu-satunya event.

Bird juga menerima balasan. Ketika pelanggan mengirim SMS ke salah satu nomor Anda, Bird menyimpan pesan dan mengirimkan sms.received, sehingga Anda dapat bertindak tanpa polling. Payload berisi isi pesan, rincian segmen, kedua nomor, dan operator jika dilaporkan oleh carrier.

Bird mengevaluasi balasan terhadap aturan kata kunci untuk nomor tersebut. Kata kunci stop yang didukung seperti STOP mencatat supresi pengirim-dan-pelanggan dan tetap mengirimkan sms.received.

Event type adalah open enum: Bird dapat menambahkan tipe event baru seiring waktu, jadi perlakukan type yang tidak dikenal sebagai event masa depan, bukan error. Tangani tipe yang Anda butuhkan dan abaikan sisanya.

Envelope event

Event tiba di endpoint webhook Anda dalam envelope bersarang Standard Webhooks yang dijelaskan di Panduan Webhooks: tiga field, type, timestamp, dan objek data yang spesifik per tipe. Identitas event tidak berada di body: ia dikirim melalui header webhook-id HTTP, yang stabil di seluruh percobaan ulang pengiriman yang sama dan merupakan kunci deduplikasi Anda.

Field	Deskripsi
type	Salah satu tipe event di halaman ini, misalnya sms.delivered
timestamp	Kapan event terjadi (RFC 3339); urutkan berdasarkan ini, jangan berdasarkan urutan kedatangan, karena pengiriman tidak berurutan
data	Payload spesifik per event

Setiap data event SMS berisi sms_id, workspace_id, serta alamat to dan from. Ia juga menggemakan tags dan metadata dari pengiriman sehingga Anda dapat merutekan dan mengorelasikan event tanpa pencarian tambahan. Masing-masing bernilai null jika pengiriman tidak menyertakannya.

Objek yang sama membawa cost, biaya pesan pada saat event tersebut, yang dipecah menjadi transaction_amount dan passthrough_amount dengan totalnya di amount. Nilainya null pada event yang tidak mengenakan biaya. Karena pengiriman tidak berurutan, gabungkan cost satu komponen pada satu waktu alih-alih mengganti seluruh objek: untuk setiap komponen, simpan nilai dari event dengan timestamp terbaru. amount hanya menjumlahkan komponen dalam payload-nya sendiri, jadi baca sebagai biaya sejauh ini, bukan total akhir. Biaya dan penagihan menjelaskan arti setiap komponen.

Contoh kode

{
  "type": "sms.delivered",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "sms_id": "sms_01krdgeqcxet5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "to": "+15551234567",
    "from": "+12025550188",
    "carrier": "Example Wireless",
    "mcc_mnc": "310260",
    "cost": {
      "amount": "0.00990",
      "currency_code": "USD",
      "transaction_amount": "0.00790",
      "passthrough_amount": "0.00200"
    },
    "tags": [{ "name": "campaign", "value": "spring-2026" }],
    "metadata": { "order_id": "ord_123" }
  }
}

Event siklus hidup

sms.accepted

Diaktifkan ketika Bird menerima pengiriman dan mulai mempersiapkan penyerahan ke operator. Payload menambahkan segments, rincian Bird yang dihitung saat penerimaan; count-nya adalah dasar penagihan pengiriman.

sms.sent

Diaktifkan ketika Bird telah menyerahkan pesan ke operator dan menunggu tanda terima pengiriman. Payload menambahkan carrier dan mcc_mnc (jaringan penangan dan kode negara/jaringan selulernya). Masing-masing tidak ada alih-alih null jika operator tidak melaporkannya. Untuk mengukur latensi pemrosesan, bandingkan timestamp event ini dengan sms.accepted.

sms.delivered

Operator mengonfirmasi pesan sampai ke perangkat. Payload menambahkan carrier dan mcc_mnc, masing-masing tidak ada jika tanda terima tidak mengidentifikasinya.

Event kegagalan

Payload setiap event kegagalan menambahkan objek error: code yang stabil di seluruh Bird (misalnya unreachable atau blocked_by_carrier), description yang mudah dibaca manusia, carrier_error_code mentah jika tersedia, dan occurred_at.

sms.undelivered

Kegagalan pengiriman non-permanen: perangkat mati atau tidak terjangkau.

sms.failed

Kegagalan pengiriman permanen menghentikan pesan.

sms.rejected

Pesan ditolak oleh pemeriksaan Bird selama pemrosesan, tagihan yang tidak bisa diselesaikan, atau operator yang menolaknya. Penolakan menghentikan pesan sebelum upaya pengiriman berhasil. Saldo habis berakhir di sini dengan kode error insufficient_balance, dan pesan yang tagihannya tidak bisa diselesaikan tidak dikenakan biaya.

sms.expired

Operator berhenti mencoba mengirim dan melaporkan pesan sebagai kedaluwarsa. Kedaluwarsa berasal dari tanda terima pengiriman operator: Bird tidak menetapkan jendela validitas sendiri dan tidak menjalankan timer yang mengakhiri pesan. error menjelaskan mengapa pesan masih belum terkirim saat operator menyerah, biasanya unreachable: perangkat tetap mati atau di luar jangkauan selama seluruh periode.

Event supresi

Di luar siklus hidup per pesan, satu event melaporkan perubahan pada daftar supresi workspace: sms_suppression.created diaktifkan saat supresi terbuka, baik pelanggan mengirim kata kunci stop, operator melaporkan opt-out, maupun seseorang menambahkannya secara manual. Payload berisi suppression_id, nomor pelanggan sebagai destination, originator yang diikat oleh blokir (supresi SMS adalah pasangan pengirim-dan-pelanggan yang tepat), reason, dan workspace_id, sehingga sistem Anda dapat mencerminkan daftar tanpa polling:

Contoh kode

{
  "type": "sms_suppression.created",
  "timestamp": "2026-08-25T14:52:03.192524705Z",
  "data": {
    "suppression_id": "ssu_01krdgeqcxet5s7t44vh8rt9mg",
    "destination": "+15550001234",
    "originator": "+15557654321",
    "reason": "keyword_stop",
    "workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf"
  }
}

Opt-out seluruh workspace yang dicatat di tab Preferences adalah preferensi yang dinyatakan, bukan supresi, dan tidak memicu event ini.

Membaca timeline pesan

Webhook mengirimkan event ke sistem Anda. Untuk peninjauan satu kali, log SMS merender aliran yang sama sebagai timeline dengan stempel waktu, detail operator, dan error. Untuk mengambil timeline secara programatik, panggil GET /v1/sms/messages/{message_id}/events. Untuk membaca status terbaru saja, panggil GET /v1/sms/messages/{message_id}.

Langkah selanjutnya

Webhooks & events: siapkan endpoint, verifikasi tanda tangan, dan tangani percobaan ulang serta replay.
Log SMS: periksa timeline per pesan yang digerakkan oleh event ini.
Mengirim SMS: atur tags dan metadata yang digemakan di setiap event.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Pahami konsepnyaOne-way and two-way SMS Jelajahi kemampuannyaTwo-way SMS Ikuti jalur pembelajaranBuild your first integration

Dapatkan ringkasan implementasi