Mga status ng WhatsApp webhook: sent, delivered, read at failed
Ang status webhooks ay nag-uulat ng nangyari sa mensaheng ipinadala ng negosyo sa pamamagitan ng WhatsApp Cloud API. Dumarating ang mga ito sa messages field na may statuses array sa halip na messages array: sent (isang check), delivered (dalawang check), read (dalawang asul na check), played para sa voice na mensahe, at failed na may errors array. Itugma ang statuses[].id sa wamid na ibinalik ng inyong send request.
Ikinokonekta ng easyCoexistence ang WhatsApp Business app na numerong gamit na ninyo sa Cloud API ng Meta sa pamamagitan ng Coexistence.
Status values na ipinapadala ng Meta: sent, delivered, read, played (unang play ng voice na mensahe) at failed.
Hiwalay na status webhooks na maaaring magawa ng isang papalabas na mensahe: sent, delivered at read.
Mula sa Graph API version na ito, inaalis ang conversation object, maliban sa mga mensaheng nasa free entry point window.
Walang API para kunin ang nakaraang webhook data; hinihiling ng Meta na i-capture at i-store ninyo ang payloads habang dumarating.
X-EC-Event header sa na-forward na status: naglalakbay ang statuses sa loob ng messages events, sa ilalim ng value.statuses.
Saan dumarating ang WhatsApp status webhooks?
Sa parehong messages field na nagdadala ng ipinapadala ng mga customer, sa parehong object, entry at changes envelope. Ang pagkakaiba ay nasa loob ng value: ang inbound na mensahe ay may messages array, habang ang status ay may statuses array. Ang handler na binabasa lamang ang value.messages ay lalaktaw sa bawat status nang walang error. Sinasabi ng metadata.phone_number_id kung aling numero ninyo ang nagpadala ng mensahe, at kasama ang contacts array na may profile name ng customer, wa_id at BSUID, maliban sa failed statuses at sa sent status ng mga group message. Ito ang halimbawa ng Meta para sa marketing template na umalis sa mga server ng 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"
}
]
}
]
}Ano ang ibig sabihin ng bawat status value?
Bawat value ay tumutugma sa marka na makikita ng customer sa WhatsApp. Ituturing lamang na read ang status kapag na-deliver na ito, at kapag tumanggap ang customer ng mensahe habang bukas na ang chat, ipinapadala ng Meta ang read nang walang delivered webhook muna, bilang internal optimization. Kaya dapat tanggapin ng tracker ang read kahit hindi dumating ang delivered, at dapat nitong i-rank ang mga status sa halip na asahan ang mga ito isa-isa sa nakapirming pagkakasunod-sunod.
Anong mga field ang dala ng status object?
Mas kaunti kaysa sa mensahe, at marami ang may kondisyon. Inililista ng reference ng Meta kung kailan naroroon ang bawat isa:
- id: ang wamid ng mensaheng ipinadala ninyo, ang susi para sa pagtutugma.
- status at timestamp: ang value at ang Unix time nang ma-trigger ang webhook, bilang string.
recipient_id: ang numero ng telepono o group id; wala ito kapag ipinadala ninyo sa BSUID at hindi available ang numero.recipient_user_id: ang BSUID ng customer; wala ito sa failed status kapag ipinadala ninyo sa numero ng telepono.recipient_typeatrecipient_participant_id: para lamang sa mga mensaheng ipinadala sa group.biz_opaque_callback_data: para lamang kapag itinakda ninyo ito sa send request.- pricing: para lamang sa sent at sa isa sa delivered o read. errors: para lamang sa failed.
Paano itugma ang status sa mensaheng ipinadala ninyo?
Sa pamamagitan ng wamid. Ibinabalik ng send request ang messages[0].id, at bawat status ng mensaheng iyon ay may parehong value sa statuses[].id. Itago ito sa tabi ng sarili ninyong record kapag nagpadala kayo, at i-update ang record kapag dumating ang statuses, habang pinapanatili ang pinakamataas na status na naabot, upang hindi ma-overwrite ng huling delivered ang read. Ang status na hindi ninyo kilala ang wamid ay ipinadala ng ibang bagay sa numero, gaya ng automation, at maaaring balewalain o i-log.
// 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));
}
}Ano ang nagbabago sa Coexistence na numero?
Inilalarawan ng statuses ang ipinadala sa pamamagitan ng API: mga sagot mula sa inyong automation, mga mensaheng ipinadala ng AI ninyo sa pamamagitan ng MCP connector, at anumang ipinadala ng sarili ninyong code. Ang tina-type ng may-ari sa WhatsApp Business app ay umaabot sa software sa ibang paraan, bilang smb_message_echoes, na dokumentado ng Meta bilang salamin ng mga mensaheng ipinadala sa app. Ang mga mensaheng dumating mula sa minsanang history import ay may sariling status sa loob ng history webhook, na may mga value tulad ng delivered, read, played, pending at error.
Pumupunta ang statuses saan man pumupunta ang messages field ng numero. Sa direct destination, diretso itong ipinapadala ng Meta sa inyong endpoint, dahil ang messages ay field na pinapayagan ng Meta na i-override ng destination. Kapag naka-on ang automations at may nakatakdang Forward URL, umaabot ang mga ito sa URL na iyon bilang messages events.
Paano nalalaman ng AI o automation ninyo kung naihatid ang mensahe?
Sa pamamagitan ng destination ninyo, hindi sa send mismo. Kapag tumawag ang assistant ng send_template o send_message, ang tool result ay may kasamang wamid at nagsasabing tinanggap ng Meta ang mensahe; kinukumpirma ang paghahatid mamaya, sa device ng customer, at iniuulat bilang status. Walang status history na maaaring i-query ang easyCoexistence, at walang MCP tool na bumabasa ng statuses, kaya ang agent na nangangailangan ng kumpirmasyon ng paghahatid ay dapat magpadala sa pamamagitan ng sistema ninyo o basahin ang statuses na natatanggap ng Forward URL ninyo.
Pareho ito sa automations: ipinapakita ng run sa Runs tab na tapos na ang reply step kapag tinanggap na ng Meta ang mensahe, at ang failure na iniulat pagkatapos ay lalabas lamang bilang failed status sa destination ninyo.
Mga karaniwang pagkakamali
- Paghahanap ng hiwalay na statuses field. Nasa messages ang statuses, kaya ang handler na binabasa lamang ang value.messages ay nawawalan nito nang walang error.
- Paghingi ng delivered bago ang read. Lalaktawan ng Meta ang delivered webhook kapag nabasa agad ang mensahe pagdating nito.
- Pagtrato sa sagot ng send bilang paghahatid. Ang wamid ay nangangahulugang tinanggap ng Meta ang request; maaaring sumunod ang failure makalipas ang ilang minuto bilang failed status.
- Pagkilala sa customer gamit lamang ang recipient_id. Wala ito kapag ipinadala ninyo sa BSUID at hindi available ang numero ng telepono; dala ng recipient_user_id ang BSUID.
Ang statuses para sa ipinapadala ng inyong automations, AI o code ay dumarating sa server ninyo: diretso mula sa Meta sa direct mode, o ipinapasa sa inyong Forward URL at nilalagdaan ng X-EC-Signature kapag naka-on ang automations, at hindi ito iniimbak bilang default. Mula US$ 9 kada naka-connect na numero kada buwan, bumababa hanggang US$ 0.75 habang dumarami ang numero, na may unang 3 araw na libre.
Mga madalas itanong
Kasama ba sa status webhooks ang teksto ng mensahe?
Hindi. Ang status ay may wamid, status, recipient, timestamps at, kung naaangkop, pricing at errors. Itago ang sarili ninyong kopya ng ipinadala, nakatala ayon sa wamid, kung kailangan ninyo itong ipakita sa tabi ng status nito.
Maaari ko bang kunin ang nakaraang statuses mula sa Meta sa susunod?
Hindi. Sinasabi ng webhook guide ng Meta na walang API para kunin ang historical webhook data, kaya ang status na hindi nakuha ng endpoint ninyo ay mawawala na kapag tumigil na ang Meta sa pag-retry, pagkatapos ng hanggang 7 araw.
Para saan ang biz_opaque_callback_data?
Ito ay string na itinatakda ninyo sa pagpapadala, gaya ng sarili ninyong order o ticket id. Ibinabalik ito ng Meta sa statuses ng mensaheng iyon, kaya maitutugma ninyo ang status sa record ninyo nang hindi muna hinahanap ang wamid.
Kailangan ko bang sumagot ng 200 sa status webhooks?
Oo, tulad ng anumang webhook POST. Itinuturing ng Meta ang anumang ibang response bilang nabigong paghahatid at inuulit ito, na isa sa mga paraan kung paano dumarating sa inyo ang parehong status nang dalawang beses.
Magpatuloy sa pagbabasa
Handa na po ba kayong magsimula?
I-set up ang WhatsApp Coexistence sa loob ng ilang minuto, hindi buwan. Patuloy na gumagana ang app sa telepono.
Magsimula ng Libreng TrialNa-verify noong