Event status pesan WhatsApp
Bird mencatat event untuk pesan WhatsApp masuk dan keluar. Lini masa keluar menunjukkan apa yang terjadi setelah pengiriman mengembalikan 202: penerimaan, penyerahan ke WhatsApp, pengiriman, pembacaan, atau kegagalan. Lini masa masuk mencatat kapan Bird menerima pesan.
Halaman ini membahas cara membaca timeline tersebut melalui API. Agar Bird mengirim setiap event ke endpoint Anda saat terjadi, lihat webhook status pesan. Reaksi memiliki riwayat tersendiri, yang dibahas di Event reaksi.
Event siklus hidup
Event muncul dalam urutan kronologis. Pesan keluar dapat berhenti di whatsapp.failed atau whatsapp.rejected, dan event whatsapp.read muncul hanya jika penerima membuka pesan. Lini masa masuk dimulai dengan whatsapp.received dan dapat mencatat whatsapp.read setelah workspace Anda menandai pesan sebagai dibaca.
| Event | Arti |
|---|---|
| whatsapp.accepted | Bird menerima permintaan kirim. Ini yang dilaporkan 202. |
| whatsapp.sent | Bird menyerahkan pesan ke jaringan WhatsApp. |
| whatsapp.delivered | WhatsApp mengonfirmasi pengiriman ke perangkat penerima. |
| whatsapp.read | Penerima membuka pesan. |
| whatsapp.failed | Pesan tidak terkirim. error.code menjelaskan penyebabnya. |
| whatsapp.rejected | Bird menolak pesan sebelum mengirimnya. Pesan tidak dikenai biaya. |
| whatsapp.received | Bird menerima pesan masuk dari kontak. |
Callback delivered atau read yang berlaku dapat memicu bagian biaya Meta. Payload event WhatsApp tidak membawa informasi biaya. Baca kembali pesan dengan GET /v1/whatsapp/messages/{message_id} untuk melihat biayanya. Lihat Biaya dan penagihan.
Menandai pesan masuk sebagai dibaca mencatat whatsapp.read di lini masanya tetapi tidak mengirimkan webhook konfirmasi baca. Pesan masuk mempertahankan status received dan mencatat read_at setelah WhatsApp menerima konfirmasi tersebut.
whatsapp.read tidak mengubah status pesan. Pesan yang terkirim tetap delivered; pesan juga mencatat pembacaan di read_at.
whatsapp.delivered dapat dilewati sepenuhnya. Ketika penerima sudah membuka chat di perangkatnya, Meta melaporkan pembacaan tanpa pernah melaporkan pengiriman, sehingga lini masa terbaca whatsapp.accepted → whatsapp.sent → whatsapp.read tanpa whatsapp.delivered di antaranya. Perlakukan read sebagai bukti pengiriman: consumer yang menunggu delivered sebelum menganggap pesan sampai akan menggantung tepat pada penerima yang paling cepat melihatnya, dan consumer yang menghitung tingkat pengiriman hanya dari delivered akan melaporkan angka lebih rendah dari seharusnya. status pesan tetap sent dalam kasus ini, karena hanya tanda terima pengiriman yang memajukannya.
Callback hanya-baca tetap dapat memicu biaya Meta yang berlaku. Bird menggunakan satu identitas biaya untuk jalur terkirim dan terbaca; event pengiriman yang tidak ada tidak berarti komponen Meta gratis. Lihat Biaya dan penagihan.
Daftar tipe event bersifat terbuka: tipe baru dapat ditambahkan seiring waktu, jadi perlakukan nilai yang tidak dikenali sebagai event masa depan, bukan kesalahan.
Event kegagalan
whatsapp.failed dan whatsapp.rejected bersifat terminal. Penolakan berarti Bird menghentikan pesan sebelum mengirimnya ke WhatsApp, sehingga tidak dikenai biaya. Penyebabnya antara lain penerima yang disupres atau memilih keluar, saldo dompet tidak mencukupi, atau tujuan tanpa harga yang dikonfigurasi. Kegagalan berarti pesan tidak terkirim, dan error.code menjelaskan siapa yang memutuskan hal itu. Sebagian besar kode membawa keputusan WhatsApp, dipetakan dari kode yang dilaporkannya. internal_error adalah pengecualian: ia mencatat kredensial pengirim yang tidak tersedia atau percobaan ulang pemrosesan yang habis. Upaya transport yang tidak pasti tidak membuktikan Meta tidak pernah menerima permintaan tersebut. meta_error_code berisi kode WhatsApp jika tersedia, dan kegagalan internal_error tidak memilikinya secara desain.
Kedua event berisi objek error dengan Bird code yang stabil, description yang dapat dibaca manusia, meta_error_code opsional, dan occurred_at. Objek ini muncul di catatan API dan payload webhook hanya untuk tipe event ini.
Membaca event dari API
GET /v1/whatsapp/messages/{message_id}/events mengembalikan lini masa dalam urutan kronologis. Daftar terbatas ini tidak dipaginasi. Membaca event memerlukan kunci API dengan whatsapp:read:
const { data } = await bird.whatsapp.listEvents("wa_abc123");
for (const event of data) console.log(event.type, event.occurred_at);events = client.whatsapp.list_events("wa_abc123")
for event in events.data:
print(event.type, event.occurred_at)events, err := client.Whatsapp.ListEvents(context.Background(), "wam_01krdgeqcxet5s7t44vh8rt9mg", bird.WhatsappListEventsParams{})
if err != nil {
log.Fatal(err)
}
for _, e := range events.Data {
fmt.Println(e.Id, e.Type)
}$events = $bird->whatsapp->listEvents('wamid_01krdgeqcxet5s7t44vh8rt9mg');
foreach ($events->getData() ?? [] as $event) {
echo $event->getType(), ' ', $event->getId(), "\n";
}bird whatsapp list-events <message-id>curl https://us1.platform.bird.com/v1/whatsapp/messages/wam_.../events \
-H "Authorization: Bearer $BIRD_API_KEY"Pesan yang diterima, dikirim, terkirim, dan dibaca mengembalikan empat event:
Contoh kode
{
"data": [
{
"id": "ev_01ky7q6a1fejfbvs0myn41hj41",
"occurred_at": "2026-07-23T14:48:34.71Z",
"type": "whatsapp.accepted"
},
{
"id": "ev_01ky7q6a2denvtd6jg1vqwmg13",
"occurred_at": "2026-07-23T14:48:35.671Z",
"type": "whatsapp.sent"
},
{
"id": "ev_01ky7q6a2zff9r2qm74mmg1g6z",
"occurred_at": "2026-07-23T14:48:36.642Z",
"type": "whatsapp.delivered"
},
{
"id": "ev_01ky7q6c21frssf0vj8h50qysw",
"occurred_at": "2026-07-23T14:48:38.65Z",
"type": "whatsapp.read"
}
]
}Berikan type untuk mengembalikan satu tipe event publik yang tepat, seperti ?type=whatsapp.failed atau ?type=whatsapp.read. Abaikan parameter ini untuk mendapatkan lini masa lengkap.
Lini masa yang sama adalah yang dirender halaman log WhatsApp saat Anda membuka pesan.
Langkah selanjutnya
- Webhook status pesan: menerima setiap event saat terjadi
- Event reaksi: membaca reaksi terkini dan log reaksi
- Tandai pesan sebagai dibaca: mengonfirmasi pesan masuk dan menampilkan indikator mengetik
- Log WhatsApp: tampilan per pesan yang merender lini masa ini
- Mengirim pesan WhatsApp: tempat siklus hidup pesan dimulai
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.
Tonton panduannyaConnecting WhatsApp to Bird: from buying a number to a live channelPahami konsepnyaWhat is the 24-hour customer service window on WhatsApp?Gunakan alatnyaWhatsApp message builderJelajahi kemampuannyaWhatsApp
Coba praktiknya dan dapatkan ringkasan implementasi