Webhook status WhatsApp: sent, delivered, read dan failed
Webhook status melaporkan apa yang terjadi pada pesan yang dikirim bisnis melalui WhatsApp Cloud API. Status tiba di field messages dengan array statuses, bukan array messages: sent (satu centang), delivered (dua centang), read (dua centang biru), played untuk pesan suara, dan failed dengan array errors. Cocokkan statuses[].id dengan wamid yang dikembalikan permintaan kirim Anda.
easyCoexistence menghubungkan nomor aplikasi WhatsApp Business yang sudah Anda gunakan ke Cloud API Meta melalui Coexistence.
Nilai status yang dikirim Meta: sent, delivered, read, played (pemutaran pertama pesan suara) dan failed.
Webhook status terpisah yang bisa dihasilkan satu pesan keluar: sent, delivered dan read.
Sejak versi Graph API ini, objek conversation dihilangkan, kecuali untuk pesan dalam jendela titik masuk gratis.
Tidak ada API untuk mengambil data webhook lama; Meta meminta Anda menangkap dan menyimpan payload saat diterima.
Header X-EC-Event pada status yang diteruskan: status dikirim di dalam event messages, di bawah value.statuses.
Ke mana webhook status WhatsApp dikirim?
Ke field messages yang sama yang membawa pesan dari pelanggan, dalam envelope object, entry, dan changes yang sama. Perbedaannya ada di dalam value: pesan masuk memiliki array messages, status memiliki array statuses. Handler yang hanya membaca value.messages akan membuang semua status tanpa kesalahan apa pun. metadata.phone_number_id menunjukkan nomor mana yang mengirim pesan, dan array contacts berisi nama profil pelanggan, wa_id, serta BSUID ikut dikirim, kecuali pada status failed dan pada status sent untuk pesan grup. Ini contoh Meta tentang template pemasaran yang telah meninggalkan server Meta:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"profile": {
"name": "Pablo M."
},
"wa_id": "16505551234",
"user_id": "US.13491208655302741918"
}
],
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
"status": "sent",
"timestamp": "1750030073",
"recipient_id": "16505551234",
"recipient_user_id": "US.13491208655302741918",
"conversation": {
"id": "72b14d6bd5407799e66f64d1b338e567",
"expiration_timestamp": "1750116480",
"origin": {
"type": "marketing"
}
},
"pricing": {
"billable": true,
"pricing_model": "PMP",
"type": "regular",
"category": "marketing"
}
}
]
},
"field": "messages"
}
]
}
]
}Apa arti setiap nilai status?
Setiap nilai sesuai dengan tanda yang akan dilihat pelanggan di WhatsApp. Status read hanya dihitung setelah delivered, dan ketika pelanggan menerima pesan saat chat sudah terbuka, Meta mengirim read tanpa webhook delivered terlebih dahulu, sebagai optimasi internal. Maka pelacak harus menerima read meskipun delivered tidak pernah datang, dan sebaiknya mengurutkan status berdasarkan tingkat kemajuannya, alih-alih mengharapkannya satu per satu dalam urutan tetap.
Field apa saja yang dibawa objek status?
Lebih sedikit dibanding pesan, dan beberapa bersifat kondisional. Referensi Meta menjelaskan kapan masing-masing ada:
- id: wamid dari pesan yang Anda kirim, kunci untuk dicocokkan.
- status dan timestamp: nilai status dan waktu Unix saat webhook dipicu, dalam bentuk string.
recipient_id: nomor telepon atau id grup, dihilangkan saat Anda mengirim ke BSUID dan nomornya tidak tersedia.recipient_user_id: BSUID pelanggan, dihilangkan pada status failed saat Anda mengirim ke nomor telepon.recipient_typedanrecipient_participant_id: hanya untuk pesan yang dikirim ke grup.biz_opaque_callback_data: hanya jika Anda mengaturnya di permintaan kirim.- pricing: hanya pada sent dan pada salah satu dari delivered atau read. errors: hanya pada failed.
Bagaimana mencocokkan status dengan pesan yang Anda kirim?
Dengan wamid. Permintaan kirim mengembalikan messages[0].id, dan setiap status untuk pesan itu membawa nilai yang sama di statuses[].id. Simpan wamid di samping catatan Anda sendiri saat mengirim, lalu perbarui catatan saat status tiba, dengan menyimpan status tertinggi yang sudah tercapai, agar delivered yang terlambat tidak menimpa read. Status dengan wamid yang tidak Anda kenal dikirim oleh sesuatu yang lain di nomor tersebut, misalnya otomasi, dan bisa diabaikan atau dicatat.
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };
// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
for (const s of value.statuses ?? []) {
const rec = sends.get(s.id); // the wamid your send request returned
if (!rec) continue; // sent by something else, such as an automation
if (s.status === "failed") {
rec.status = "failed";
rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
} else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
rec.status = s.status; // read arriving before delivered is fine; never step back
}
rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
}
}Apa yang berubah pada nomor Coexistence?
Status menggambarkan apa yang dikirim melalui API: balasan dari otomasi Anda, pesan yang dikirim AI Anda melalui konektor MCP, dan apa pun yang dikirim kode Anda sendiri. Pesan yang diketik pemilik di aplikasi WhatsApp Business sampai ke perangkat lunak dengan cara berbeda, sebagai smb_message_echoes, yang oleh Meta didokumentasikan sebagai cermin pesan yang dikirim dari aplikasi. Pesan yang masuk lewat impor riwayat satu kali memiliki status sendiri di dalam webhook riwayat, dengan nilai seperti delivered, read, played, pending, dan error.
Status dikirim ke mana pun field messages nomor itu menuju. Dengan tujuan langsung, Meta mengirimnya langsung ke endpoint Anda, karena messages adalah field yang boleh ditimpa oleh tujuan. Dengan otomasi aktif dan Forward URL diatur, status sampai ke URL itu sebagai event messages.
Bagaimana AI atau otomasi Anda tahu apakah pesan sudah sampai ke pelanggan?
Melalui tujuan Anda, bukan melalui pengiriman. Ketika asisten memanggil send_template atau send_message, hasil tool membawa wamid dan menyatakan Meta menerima pesan; pesan yang sampai dikonfirmasi kemudian, di perangkat pelanggan, dan dilaporkan sebagai status. easyCoexistence tidak menyimpan riwayat status untuk ditanyakan, dan tidak ada tool MCP yang membaca status, jadi agen yang memerlukan konfirmasi pesan sampai sebaiknya mengirim melalui sistem Anda atau membaca status yang diterima Forward URL Anda.
Hal yang sama berlaku untuk otomasi: eksekusi di tab Runs menampilkan langkah balasan sebagai selesai begitu Meta menerima pesan, dan kegagalan yang dilaporkan setelahnya hanya muncul sebagai status failed di tujuan Anda.
Kesalahan umum
- Mencari field statuses yang terpisah. Status datang lewat messages, sehingga handler yang hanya membaca value.messages kehilangannya tanpa kesalahan apa pun.
- Mewajibkan delivered sebelum read. Meta melewati webhook delivered ketika pesan langsung dibaca saat tiba.
- Menganggap respons kirim sebagai bukti pesan sampai. wamid berarti Meta menerima permintaan; kegagalan bisa menyusul beberapa menit kemudian sebagai status failed.
- Mengidentifikasi pelanggan hanya dengan recipient_id. Field itu dihilangkan saat Anda mengirim ke BSUID dan nomor telepon tidak tersedia; recipient_user_id membawa BSUID.
Status untuk apa yang dikirim otomasi, AI, atau kode Anda sampai ke server Anda: langsung dari Meta dalam mode langsung, atau diteruskan ke Forward URL Anda dan ditandatangani dengan X-EC-Signature saat otomasi aktif, dan tidak disimpan secara default. US$ 9 turun ke US$ 0.75 per nomor per bulan, makin turun seiring Anda menambah nomor, dengan 3 hari pertama gratis.
Pertanyaan yang sering diajukan
Apakah webhook status menyertakan teks pesan?
Tidak. Status berisi wamid, status, penerima, timestamp, dan jika berlaku, pricing dan errors. Simpan salinan sendiri dari apa yang Anda kirim, dengan kunci wamid, jika Anda perlu menampilkannya di samping statusnya.
Bisakah saya mengambil status lama dari Meta nanti?
Tidak. Panduan webhook Meta menyatakan tidak ada API untuk mengambil data webhook historis, sehingga status yang tidak ditangkap endpoint Anda hilang setelah Meta berhenti mencoba kembali, paling lama setelah 7 hari.
Untuk apa biz_opaque_callback_data?
Itu string yang Anda atur saat mengirim, misalnya id pesanan atau tiket Anda sendiri. Meta mengembalikannya di statuses pesan tersebut, sehingga Anda bisa mencocokkan status dengan catatan Anda tanpa mencari wamid lebih dulu.
Apakah saya harus membalas webhook status dengan 200?
Ya, seperti webhook POST lainnya. Meta menganggap respons lain sebagai pengiriman gagal dan mencoba kembali, dan itulah salah satu cara status yang sama sampai ke Anda dua kali.
Lanjut membaca
Siap memulai?
Konfigurasikan WhatsApp Coexistence dalam hitungan menit, bukan bulan. Aplikasi tetap berfungsi di ponsel.
Mulai uji coba gratisDiverifikasi pada