WhatsApp statusi webhookova: poslano, dostavljeno, pročitano i neuspjelo
Statusni webhookovi javljaju što se dogodilo s porukom koju je tvrtka poslala putem WhatsApp Cloud API-ja. Stižu na polju messages, ali umjesto niza messages sadrže niz statuses: poslano (jedna kvačica), dostavljeno (dvije kvačice), pročitano (dvije plave kvačice), reproducirano za glasovne poruke te neuspjelo s nizom errors. Usporedite statuses[].id s wamid-om koji je zahtjev za slanje vratio.
easyCoexistence povezuje broj WhatsApp Business aplikacije koji već koristite s Metinim Cloud API-jem uz Coexistence.
Vrijednosti statusa koje Meta šalje: sent, delivered, read, played (prvo reproduciranje glasovnih poruka) i failed.
Odvojeni webhookovi statusa koje jedna odlazna poruka može proizvesti: sent, delivered i read.
Od ove verzije Graph API-ja objekt conversation se izostavlja, osim za poruke unutar prozora ulazne točke bez naplate.
Ne postoji API za dohvat prošlih webhook podataka; Meta traži da payloade zabilježite i pohranite čim stignu.
Zaglavlje X-EC-Event na proslijeđenom statusu: statusi putuju unutar događaja messages, pod value.statuses.
Gdje stižu statusni webhookovi WhatsAppa?
Na istom polju messages koje nosi ono što šalju kupci, u istom objektu, u istoj omotnici entry i changes. Razlika je unutar value: dolazna poruka ima niz messages, a status ima niz statuses. Handler koji čita samo value.messages bez ikakve pogreške odbacuje svaki status. metadata.phone_number_id kaže koji je vaš broj poslao poruku, a dolazi i niz contacts s profilnim imenom kupca, wa_id-om i BSUID-om, osim kod neuspjelih statusa i kod statusa sent za grupne poruke. Ovo je Metin primjer predloška poruke koja je napustila Metine poslužitelje:
{
"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"
}
]
}
]
}Što znači svaka vrijednost statusa?
Svaka vrijednost odgovara oznaci koju bi kupac vidio u WhatsAppu. Status se smatra pročitanim tek kad je poruka isporučena, a kad kupac primi poruku dok je razgovor već otvoren, Meta šalje read bez prethodnog webhooka delivered, kao unutarnju optimizaciju. Zato praćenje mora prihvatiti read i kad delivered nikad nije stigao te mora rangirati statuse umjesto da ih očekuje jedan po jedan u fiksnom slijedu.
Koja polja nosi objekt statusa?
Manje nego poruka, a nekoliko ih je uvjetno. Metin referentni vodič navodi kad je svako prisutno:
- id: wamid poruke koju ste poslali, ključ po kojem se usklađuje.
- status i timestamp: vrijednost i Unix vrijeme okidanja webhooka, kao tekst.
recipient_id: broj telefona ili ID grupe, izostavlja se kad ste slali na BSUID i broj nije dostupan.recipient_user_id: BSUID kupca, izostavlja se kod neuspjelog statusa kad ste slali na broj telefona.recipient_typeirecipient_participant_id: samo za poruke poslane grupi.biz_opaque_callback_data: samo kad ste ga postavili u zahtjevu za slanje.- pricing: samo kod sent i jednog od delivered ili read. errors: samo kod failed.
Kako povezati status s porukom koju ste poslali?
Pomoću wamid-a. Zahtjev za slanje vraća messages[0].id, a svaki status za tu poruku nosi istu vrijednost u statuses[].id. Spremite je uz vlastiti zapis pri slanju, zatim ažurirajte zapis kad stignu statusi, držeći najviši dosegnuti status, da kasni delivered ne prepiše read. Status čiji wamid ne poznajete poslalo je nešto drugo na broju, primjerice neka automatizacija, pa ga možete zanemariti ili zabiljež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));
}
}Što se mijenja kod Coexistence broja?
Statusi opisuju što je poslano putem API-ja: odgovore vaših automatizacija, poruke koje je vaša AI poslala kroz MCP konektor i sve što je poslao vaš vlastiti kod. Ono što vlasnik upiše u aplikaciji WhatsApp Business do softvera stiže drugim putem, kao smb_message_echoes, za koje Meta dokumentira da je zrcalo poruka poslanih iz aplikacije. Poruke preuzete u jednokratnom uvozu povijesti nose vlastiti status unutar webhooka povijesti, s vrijednostima poput delivered, read, played, pending i error.
Statusi idu kamo ide polje messages tog broja. Uz izravno odredište Meta ih šalje ravno na vašu krajnju točku, jer je messages polje koje odredište smije nadjačati. Kad su automatizacije uključene i postavljen je Forward URL, stižu na taj URL kao događaji messages.
Kako vaša AI ili automatizacija saznaje je li poruka isporučena?
Kroz vaše odredište, a ne kroz slanje. 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 kupčevu uređaju, i javlja se kao status. easyCoexistence ne čuva povijest statusa za upit, a nijedan MCP alat ne čita statuse, pa agent kojem treba potvrda isporuke mora slati kroz vaš sustav ili čitati statuse koje prima vaš Forward URL.
Isto vrijedi za automatizacije: izvođenje na kartici Runs pokazuje korak odgovora završenim čim je Meta prihvatila poruku, a neuspjeh javljen naknadno pojavljuje se samo kao neuspjeli status na vašem odredištu.
Uobičajene pogreške
- Traženje zasebnog polja statuses. Statusi dolaze na messages, pa handler koji čita samo value.messages gubi ih bez ikakve pogreške.
- Zahtijevanje delivered prije read. Meta preskače webhook delivered kad se poruka pročita čim stigne.
- Tretiranje odgovora na slanje kao isporuke. Wamid znači da je Meta prihvatila zahtjev; neuspjeh može uslijediti minutama kasnije kao neuspjeli status.
- Vezanje kupaca samo uz recipient_id. Izostavlja se kad ste slali na BSUID i broj telefona nije dostupan; recipient_user_id nosi BSUID.
Statusi za ono što šalju vaše automatizacije, vaša AI ili vaš kod stižu na vaš poslužitelj: izravno od Mete u izravnom načinu rada ili proslijeđeni na vaš Forward URL i potpisani zaglavljem X-EC-Signature kad su automatizacije uključene, a ne čuvaju se kao zadano. Od US$ 9 po povezanom broju mjesečno, uz pad na US$ 0,75 kako dodajete brojeve, te besplatno probno razdoblje od 3 dana.
Često postavljana pitanja
Sadrže li statusni webhookovi tekst poruke?
Ne. Status nosi wamid, status, primatelja, vremenske oznake i, ako se primjenjuju, cijenu i pogreške. Zadržite vlastitu kopiju onoga što ste poslali, uz wamid kao ključ, ako to trebate prikazati uz status.
Mogu li kasnije dohvatiti prošle statuse od Mete?
Ne. Metin vodič za webhookove kaže da ne postoje API-ji za dohvat povijesnih podataka webhookova, pa status koji vaša krajnja točka nije zabilježila nestaje kad Meta prestane ponavljati pokušaje, nakon do 7 dana.
Čemu služi biz_opaque_callback_data?
To je tekst koji postavljate pri slanju, primjerice vaš broj narudžbe ili ulaznice. Meta ga vraća u statusima te poruke, pa status možete usporediti sa svojim zapisom bez prethodnog traženja wamid-a.
Moram li na statusne webhookove odgovoriti s 200?
Da, kao i na svaki webhook POST. Meta svaki drugi odgovor tretira kao neuspjelu isporuku i ponavlja je, što je jedan od načina na koje isti status stigne dvaput.
Nastavite čitati
Spremni za početak?
Postavite WhatsApp Coexistence u nekoliko minuta, a ne mjeseci. Aplikacija i dalje radi na telefonu.
Započnite besplatno probno razdobljeProvjereno na