Status webhook WhatsApp: dihantar, diterima, dibaca dan gagal
Webhook status melaporkan apa yang berlaku kepada mesej yang dihantar oleh perniagaan melalui WhatsApp Cloud API. Ia tiba pada medan messages dengan tatasusunan statuses, bukan tatasusunan messages: dihantar (satu tanda semak), diterima (dua tanda semak), dibaca (dua tanda semak biru), dimainkan untuk mesej suara, dan gagal dengan tatasusunan errors. Padankan statuses[].id dengan wamid yang dikembalikan oleh permintaan hantar anda.
easyCoexistence menyambungkan nombor aplikasi WhatsApp Business yang sudah anda guna kepada Cloud API Meta melalui Coexistence.
Nilai status yang dihantar Meta: sent, delivered, read, played (main pertama bagi mesej suara) dan failed.
Webhook status berasingan yang boleh dihasilkan oleh satu mesej keluar: sent, delivered dan read.
Bermula dari versi Graph API ini, objek conversation ditinggalkan, kecuali bagi mesej dalam tetingkap titik kemasukan percuma.
Tiada API untuk mengambil data webhook lama; Meta meminta anda menangkap dan menyimpan payload semasa ia tiba.
Header X-EC-Event pada status yang diteruskan: status dibawa dalam peristiwa messages, di bawah value.statuses.
Di manakah webhook status WhatsApp tiba?
Pada medan messages yang sama yang membawa apa yang dihantar pelanggan, dalam objek, entry dan sampul changes yang sama. Perbezaannya ada dalam value: mesej masuk mempunyai tatasusunan messages, status mempunyai tatasusunan statuses. Pengendali yang hanya membaca value.messages akan menggugurkan setiap status tanpa ralat. metadata.phone_number_id menyatakan nombor mana daripada anda yang menghantar mesej, dan tatasusunan contacts dengan nama profil pelanggan, wa_id dan BSUID turut disertakan, kecuali pada status gagal dan pada status dihantar bagi mesej kumpulan. Ini ialah contoh Meta bagi templat pemasaran yang telah keluar dari pelayan 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 maksud setiap nilai status?
Setiap nilai sepadan dengan tanda yang akan dilihat pelanggan dalam WhatsApp. Status dikira dibaca hanya selepas ia telah diterima, dan apabila pelanggan menerima mesej semasa sembang sudah terbuka, Meta menghantar read tanpa webhook delivered terlebih dahulu, sebagai pengoptimuman dalaman. Oleh itu, penjejak perlu menerima read walaupun delivered tidak pernah tiba, dan perlu menyusun status mengikut kedudukannya, bukan menjangkakan setiap status satu demi satu dalam urutan tetap.
Medan apa yang dibawa oleh objek status?
Lebih sedikit daripada mesej, dan beberapa medan bersyarat. Rujukan Meta menyatakan bila setiap satu hadir:
- id: wamid mesej yang anda hantar, kunci untuk dipadankan.
- status dan timestamp: nilai dan masa Unix ketika webhook dicetuskan, sebagai rentetan.
recipient_id: nombor telefon atau id kumpulan, ditinggalkan apabila anda menghantar kepada BSUID dan nombor tidak tersedia.recipient_user_id: BSUID pelanggan, ditinggalkan pada status gagal apabila anda menghantar kepada nombor telefon.recipient_typedanrecipient_participant_id: hanya bagi mesej yang dihantar kepada kumpulan.biz_opaque_callback_data: hanya apabila anda menetapkannya dalam permintaan hantar.- pricing: hanya pada sent dan pada salah satu daripada delivered atau read. errors: hanya pada failed.
Bagaimana anda memadankan status dengan mesej yang anda hantar?
Melalui wamid. Permintaan hantar mengembalikan messages[0].id, dan setiap status bagi mesej itu membawa nilai yang sama dalam statuses[].id. Simpan ia bersebelahan rekod anda sendiri semasa menghantar, kemudian kemas kini rekod apabila status tiba, dengan mengekalkan status tertinggi yang dicapai, supaya delivered lewat tidak menimpa read. Status yang wamidnya tidak anda kenali dihantar oleh sesuatu yang lain pada nombor itu, seperti automasi, dan boleh diabaikan atau dilog.
// 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 nombor Coexistence?
Status menerangkan apa yang dihantar melalui API: balasan daripada automasi anda, mesej yang dihantar AI anda melalui penyambung MCP, dan apa sahaja yang dihantar oleh kod anda sendiri. Apa yang ditaip oleh pemilik dalam aplikasi WhatsApp Business sampai ke perisian dengan cara yang berbeza, sebagai smb_message_echoes, yang didokumentasikan Meta sebagai cermin bagi mesej yang dihantar melalui aplikasi. Mesej yang dibawa masuk dalam import sejarah sekali sahaja membawa status sendiri dalam webhook sejarah, dengan nilai seperti delivered, read, played, pending dan error.
Status pergi ke mana sahaja medan messages nombor itu pergi. Dengan destinasi terus, Meta menghantarnya terus ke endpoint anda, kerana messages ialah medan yang Meta benarkan destinasi tolak. Dengan automasi dihidupkan dan URL Forward ditetapkan, status sampai ke URL itu sebagai peristiwa messages.
Bagaimana AI atau automasi anda tahu sama ada mesej telah dihantar?
Melalui destinasi anda, bukan melalui penghantaran. Apabila pembantu memanggil send_template atau send_message, hasil alat membawa wamid dan menyatakan Meta menerima mesej; penghantaran disahkan kemudian, pada peranti pelanggan, dan dilaporkan sebagai status. easyCoexistence tidak menyimpan sejarah status untuk ditanya, dan tiada alat MCP membaca status, jadi ejen yang memerlukan pengesahan penghantaran hendaklah menghantar melalui sistem anda atau membaca status yang diterima oleh Forward URL anda.
Begitu juga dengan automasi: larian dalam tab Runs menunjukkan langkah balasan selesai apabila Meta menerima mesej, dan kegagalan yang dilaporkan kemudian hanya muncul sebagai status gagal di destinasi anda.
Kesilapan biasa
- Mencari medan statuses yang berasingan. Status datang pada messages, jadi pengendali yang hanya membaca value.messages kehilangannya tanpa sebarang ralat.
- Menghendaki delivered sebelum read. Meta melangkau webhook delivered apabila mesej dibaca sebaik sahaja ia tiba.
- Menganggap respons hantar sebagai penghantaran. Wamid bermakna Meta menerima permintaan; kegagalan boleh menyusul beberapa minit kemudian sebagai status gagal.
- Mengenal pasti pelanggan hanya melalui recipient_id. Ia ditinggalkan apabila anda menghantar kepada BSUID dan nombor telefon tidak tersedia; recipient_user_id membawa BSUID.
Status bagi apa yang dihantar oleh automasi, AI atau kod anda pergi ke pelayan anda: terus dari Meta dalam mod terus, atau diteruskan ke Forward URL anda dan ditandatangani dengan X-EC-Signature apabila automasi dihidupkan, dan tidak disimpan secara lalai. Harga daripada US$ 9 turun kepada US$ 0.75 setiap nombor sebulan, menurun apabila anda menambah nombor, dengan percubaan percuma 3 hari pertama.
Soalan lazim
Adakah webhook status mengandungi teks mesej?
Tidak. Status membawa wamid, status, penerima, cap masa dan, di mana berkenaan, harga dan ralat. Simpan salinan anda sendiri bagi apa yang dihantar, dikunci mengikut wamid, jika anda perlu memaparkannya bersebelahan statusnya.
Bolehkah saya mengambil status lepas daripada Meta kemudian?
Tidak. Panduan webhook Meta menyatakan tiada API untuk mengambil data webhook sejarah, jadi status yang tidak ditangkap oleh endpoint anda hilang selepas Meta berhenti mencuba semula, sehingga 7 hari.
Untuk apakah biz_opaque_callback_data?
Ia ialah rentetan yang anda tetapkan semasa menghantar, seperti id pesanan atau tiket anda sendiri. Meta mengembalikannya dalam statuses mesej itu, jadi anda boleh memadankan status dengan rekod anda tanpa mencari wamid dahulu.
Adakah saya perlu membalas webhook status dengan 200?
Ya, seperti mana-mana POST webhook. Meta menganggap sebarang respons lain sebagai penghantaran gagal dan mencuba semula, dan itulah salah satu cara status yang sama sampai kepada anda dua kali.
Teruskan membaca
Sedia untuk bermula?
Sediakan WhatsApp Coexistence dalam beberapa minit, bukan berbulan-bulan. Aplikasi terus berfungsi pada telefon.
Mulakan Percubaan PercumaDisahkan pada