WhatsApp webhook statusi: poslato, isporučeno, pročitano i neuspelo
Status webhookovi javljaju šta se dogodilo s porukom koju je firma poslala preko WhatsApp Cloud API-ja. Stižu u polju messages sa nizom statuses umesto niza messages: poslato (jedna kvačica), isporučeno (dve kvačice), pročitano (dve plave kvačice), reprodukovano za glasovne poruke i neuspelo, sa nizom errors. Uskladite statuses[].id sa wamid-om koji je zahtev za slanje vratio.
easyCoexistence povezuje broj WhatsApp Business aplikacije koji već koristite sa Metinim Cloud API-jem preko Coexistence.
Vrednosti statusa koje Meta šalje: sent, delivered, read, played (prvo reprodukovanje glasovnih poruka) i failed.
Odvojeni webhookovi statusa koje jedna odlazna poruka može da proizvede: sent, delivered i read.
Od ove verzije Graph API-ja objekat conversation se izostavlja, osim za poruke u besplatnom prozoru ulazne tačke.
Nema API-ja za preuzimanje prošlih podataka webhookova; Meta traži da payloade čuvate čim stignu.
Zaglavlje X-EC-Event na prosleđenom statusu: statusi putuju unutar događaja messages, pod value.statuses.
Gde stižu WhatsApp webhookovi statusa?
U istom polju messages koje nosi ono što šalju korisnici, u istom objektu, okviru entry i changes. Razlika je unutar value: dolazna poruka ima niz messages, a status ima niz statuses. Obrađivač koji čita samo value.messages bez greške izostavlja svaki status. metadata.phone_number_id kazuje koji je vaš broj poslao poruku, a dolazi i niz contacts sa imenom profila korisnika, wa_id i BSUID-om, osim kod neuspelih statusa i kod statusa sent za grupne poruke. Ovo je Metin primer šablona marketinške poruke koja je napustila Metine servere:
{
"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"
}
]
}
]
}Šta znači svaka vrednost statusa?
Svaka vrednost odgovara oznaci koju bi korisnik video u WhatsApp-u. Status se računa kao pročitan tek kad je isporučen, a kad korisnik primi poruku dok je razgovor već otvoren, Meta šalje read bez prethodnog webhooka delivered, kao internu optimizaciju. Zato praćenje treba da prihvati read čak i kad delivered nikad nije stigao, i da statuse rangira umesto da očekuje svaki redom u fiksnom nizu.
Koja polja nosi objekat statusa?
Manje nego poruka, a nekoliko je uslovno. Metina referenca navodi kada je svako prisutno:
- id: wamid poruke koju ste poslali, ključ za uparivanje.
- status i timestamp: vrednost i Unix vreme kada je webhook pokrenut, kao string.
recipient_id: broj telefona ili id grupe, izostavlja se kad ste slali na BSUID a broj nije dostupan.recipient_user_id: BSUID korisnika, izostavlja se kod neuspelog statusa kad ste slali na broj telefona.recipient_typeirecipient_participant_id: samo za poruke poslate grupi.biz_opaque_callback_data: samo ako ste ga postavili u zahtevu za slanje.- pricing: samo kod sent i kod jednog od delivered ili read. errors: samo kod failed.
Kako uparujete status sa porukom koju ste poslali?
Preko wamid-a. Zahtev za slanje vraća messages[0].id, a svaki status za tu poruku nosi istu vrednost u statuses[].id. Sačuvajte je uz svoj zapis kad šaljete, pa zapis ažurirajte kad stignu statusi, zadržavajući najviši dostignuti status, da kasno delivered ne prepiše read. Status čiji wamid ne poznajete poslalo je nešto drugo na broju, na primer automatizacija, i može se zanemariti ili zabeležiti.
// 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));
}
}Šta se menja na Coexistence broju?
Statusi opisuju ono što je poslato preko API-ja: odgovori vaših automatizacija, poruke koje je vaš AI poslao preko MCP konektora i sve što je poslao vaš kod. Ono što vlasnik ukuca u aplikaciji WhatsApp Business stiže softveru drugačije, kao smb_message_echoes, za koje Meta dokumentuje da su ogledalo poruka poslatih iz aplikacije. Poruke preuzete pri jednokratnom uvozu istorije nose sopstveni status unutar webhooka istorije, sa vrednostima kao što su delivered, read, played, pending i error.
Statusi idu tamo gde ide polje messages tog broja. Kod direktnog odredišta Meta ih šalje pravo na vaš endpoint, jer je messages polje koje Meta dozvoljava da odredište zameni. Kad su automatizacije uključene i postavljen je Forward URL, stižu na taj URL kao događaji messages.
Kako AI ili automatizacija saznaje da je poruka isporučena?
Preko vašeg odredišta, a ne preko slanja. Kad asistent pozove send_template ili send_message, rezultat alata nosi wamid i kaže da je Meta prihvatila poruku; isporuka se potvrđuje kasnije, na uređaju korisnika, i javlja se kao status. easyCoexistence ne čuva istoriju statusa za upit, a nijedan MCP alat ne čita statuse, pa agent kojem treba potvrda isporuke treba da šalje preko vašeg sistema ili da čita statuse koje prima vaš Forward URL.
Isto važi i za automatizacije: izvršavanje na kartici Runs pokazuje korak odgovora završenim čim je Meta prihvatila poruku, a greška prijavljena posle se pojavljuje samo kao status failed na vašem odredištu.
Česte greške
- Traženje zasebnog polja statuses. Statusi dolaze u messages, pa obrađivač koji čita samo value.messages gubi ih bez ikakve greške.
- Zahtevanje delivered pre read. Meta preskače webhook delivered kad je poruka pročitana čim stigne.
- Tretiranje odgovora na slanje kao isporuke. Wamid znači da je Meta prihvatila zahtev; greška može da sledi minutima kasnije kao status failed.
- Vezivanje korisnika samo za recipient_id. Izostavlja se kad ste slali na BSUID a broj telefona nije dostupan; recipient_user_id nosi BSUID.
Statusi za ono što šalju vaše automatizacije, vaš AI ili vaš kod stižu na vaš server: direktno od Mete u direktnom režimu, ili prosleđeni na vaš Forward URL i potpisani sa X-EC-Signature kad su automatizacije uključene, i ne čuvaju se podrazumevano. Od US$ 9 do US$ 0,75 po broju mesečno, uz pad kako dodajete brojeve, sa prvih 3 dana besplatno.
Često postavljana pitanja
Da li webhookovi statusa sadrže tekst poruke?
Ne. Status nosi wamid, status, primaoca, vremenske oznake i, kad se primenjuje, cene i greške. Ako vam treba da prikažete tekst uz status, čuvajte sopstvenu kopiju onoga što ste poslali, po wamid-u.
Mogu li kasnije da preuzmem prošle statuse od Mete?
Ne. Metin vodič za webhookove kaže da ne postoje API-ji za preuzimanje istorijskih podataka webhookova, pa status koji vaš endpoint nije zabeležio nestaje kad Meta prestane da ponavlja slanje, posle najviše 7 dana.
Čemu služi biz_opaque_callback_data?
To je string koji postavljate pri slanju, na primer vaš broj narudžbine ili tiketa. Meta ga vraća u statuses te poruke, pa status možete upariti sa svojim zapisom bez prethodnog traženja wamid-a.
Moram li da odgovorim na webhookove statusa sa 200?
Da, kao i na svaki webhook POST. Meta bilo koji drugi odgovor tretira kao neuspelu isporuku i ponavlja je, što je jedan od načina da isti status stigne dvaput.
Nastavite sa čitanjem
Spremni da počnete?
Podesite WhatsApp Coexistence za nekoliko minuta, a ne meseci. Aplikacija nastavlja da radi na telefonu.
Započnite besplatni probni periodProvereno na