WhatsApp webhook statuses: sent, delivered, read සහ failed
Status webhook මගින් WhatsApp Cloud API හරහා ව්යාපාරයක් යැවූ පණිවිඩයකට සිදු වූ දේ වාර්තා කරයි. ඒවා messages field එක මත පැමිණෙන නමුත් messages array එක වෙනුවට statuses array එකක් ඇතුළත් වේ: sent (check එකක්), delivered (check දෙකක්), read (නිල් check දෙකක්), voice පණිවිඩ සඳහා played, සහ errors array එකක් සහිත failed. statuses[].id ඔබේ send request එක මගින් ලැබුණු wamid සමඟ ගළපන්න.
easyCoexistence ඔබ දැනට භාවිතා කරන WhatsApp Business app අංකය Coexistence හරහා Meta හි Cloud API වෙත සම්බන්ධ කරයි.
Meta එවන status අගයන්: sent, delivered, read, played (voice messages හි පළමු play එක) සහ failed.
එක outgoing පණිවිඩයකට උත්පාදනය විය හැකි වෙනම status webhooks: sent, delivered සහ read.
මෙම Graph API version සිට conversation object ඉවත් කර ඇත, free entry point window එකක පණිවිඩ හැර.
Past webhook දත්ත ලබා ගැනීමට APIs නොමැත; payloads ලැබෙන සැණින් ග්රහණය කර ගබඩා කරන ලෙස Meta ඉල්ලා සිටී.
Forward කළ status මත X-EC-Event header එක: statuses ගමන් කරන්නේ messages events තුළ, value.statuses යටතේ.
WhatsApp status webhooks ලැබෙන්නේ කොතැනින් ද?
ගනුදෙනුකරුවන් එවන දේ රැගෙන එන එම messages field මතම, එම object, entry සහ changes envelope තුළම. වෙනස value තුළ පවතී: ඇතුළත් පණිවිඩයක messages array එකක් ඇති අතර status එකක statuses array එකක් ඇත. value.messages පමණක් කියවන handler එකක් කිසිදු දෝෂයක් නොමැතිව සියලු status අත්හරියි. metadata.phone_number_id යනු ඔබේ කුමන අංකයකින් පණිවිඩය යැවුවාද යන්න කියයි, සහ ගනුදෙනුකරුගේ profile name, wa_id සහ BSUID අඩංගු contacts array එකක් ද ලැබේ, failed status හි සහ group පණිවිඩවල sent status හි හැර. Meta සපයන උදාහරණය: Meta සේවාදායකයින්ගෙන් පිටව ගිය marketing template එකකි:
{
"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"
}
]
}
]
}සෑම status අගයක් ම කුමක් අදහස් කරයි?
සෑම අගයක් ම ගනුදෙනුකරුට WhatsApp හි පෙනෙන සලකුණකට ගැලපේ. status එකක් read ලෙස ගණන් ගැනෙන්නේ එය delivered වූ පසුව පමණි; ගනුදෙනුකරුට පණිවිඩයක් ලැබෙන විට chat එක දැනටමත් විවෘත නම්, Meta අභ්යන්තර ප්රශස්තකරණයක් ලෙස delivered webhook එකක් නොමැතිව read යවයි. එබැවින් tracker එකක් delivered නොපැමිණියත් read පිළිගත යුතු අතර, statuses ස්ථිර අනුපිළිවෙලකින් බලාපොරොත්තු වෙනවා වෙනුවට ඒවා ශ්රේණිගත කළ යුතුය.
status object එකක ඇති fields මොනවා ද?
පණිවිඩයකට වඩා අඩුය, සහ කිහිපයක් කොන්දේසි සහිතයි. Meta හි යොමුවෙහි එක් එක් field කවදා තිබේද යන්න ලැයිස්තුගත කර ඇත:
- id: ඔබ යැවූ පණිවිඩයේ wamid, ගැලපීමේ යතුර.
- status සහ timestamp: අගය සහ webhook ක්රියාත්මක වූ Unix වේලාව, string එකක් ලෙස.
recipient_id: දුරකථන අංකය හෝ group id, BSUID වෙත යැවූ විට සහ අංකය ලබා ගත නොහැකි විට ඉවත් කර ඇත.recipient_user_id: ගනුදෙනුකරුගේ BSUID, දුරකථන අංකයට යැවූ විට failed status හි ඉවත් කර ඇත.recipient_typeසහrecipient_participant_id: group වෙත යැවූ පණිවිඩ සඳහා පමණි.biz_opaque_callback_data: send request හි ඔබ එය සකසූ විට පමණි.- pricing: sent මත සහ delivered හෝ read එක මත පමණි. errors: failed මත පමණි.
යැවූ පණිවිඩයට status එක ගැලපෙන්නේ කෙසේ ද?
wamid මගින්. send request එක messages[0].id සමඟ පිළිතුරු දෙන අතර, එම පණිවිඩයේ සෑම status එකක් ම statuses[].id හි එම අගය රැගෙන යයි. send කරන විට එය ඔබේ වාර්තාව අසල ගබඩා කර, status පැමිණෙන විට වාර්තාව යාවත්කාලීන කරන්න. එහිදී ළඟා වූ ඉහළම status එක තබාගන්න, එවිට පසුව පැමිණි delivered එකක් read එක නැවත ලිවීම නොකරයි. ඔබ නොදන්නා wamid එකක status එකක් වෙනත් දෙයකින් යවා ඇත, උදාහරණයක් ලෙස automation එකක්, එබැවින් එය නොසලකා හැරිය හැක හෝ 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));
}
}Coexistence අංකයක දී කුමක් වෙනස් වේ ද?
Statuses විස්තර කරන්නේ API හරහා යැවූ දේ: ඔබේ automations වලින් පිළිතුරු, MCP connector හරහා AI එක යැවූ පණිවිඩ, සහ ඔබේ කේතය යැවූ ඕනෑම දෙයක්. WhatsApp Business app එකේ හිමිකරු ටයිප් කරන දේ මෘදුකාංගයට වෙනස් ලෙස පැමිණේ, smb_message_echoes ලෙස, එය app එකෙන් යවන ලද පණිවිඩවල කැඩපත ලෙස Meta ලේඛනගත කර ඇත. එක් වරක් ආනයනය කළ ඉතිහාස පණිවිඩවලට history webhook තුළ තමන්ගේම status එකක් ඇත, delivered, read, played, pending සහ error වැනි අගයන් සමඟ.
Statuses messages field එක ගමන් කරන ඕනෑම තැනකට යයි. Direct destination එකක දී Meta ඒවා ඔබේ endpoint එකට කෙලින්ම යවයි, මන්ද messages යනු Meta destination එකකට override කළ හැකි field එකකි. Automations සක්රිය කර Forward URL එකක් සකස් කළ විට, ඒවා එම URL එකට messages events ලෙස ළඟා වේ.
ඔබේ AI හෝ automation පණිවිඩය බෙදා හරින ලද ද යන්න දැන ගන්නේ කෙසේ ද?
ඔබේ destination හරහා, send හරහා නොවේ. assistant එකක් send_template හෝ send_message කැඳවන විට, tool result එකේ wamid අඩංගු වන අතර Meta පණිවිඩය පිළිගත් බව කියයි; බෙදා හැරීම පසුව ගනුදෙනුකරුගේ උපාංගයේ තහවුරු වී status එකක් ලෙස වාර්තා වේ. easyCoexistence විමසිය හැකි status ඉතිහාසයක් තබා ගන්නේ නැත, සහ කිසිදු MCP tool එකක් statuses කියවන්නේ නැත, එබැවින් බෙදා හැරීමේ තහවුරු කිරීම අවශ්ය agent එකක් ඔබේ පද්ධතිය හරහා යැවිය යුතුය, හෝ ඔබේ Forward URL එක ලබා ගන්නා statuses කියවිය යුතුය.
Automations සඳහා ද එයම වේ: Runs tab එකේ run එකක් reply step එක done ලෙස පෙන්වන්නේ Meta පණිවිඩය පිළිගත් විට; පසුව වාර්තා වන අසාර්ථකතාවක් ඔබේ destination එකේ failed status එකක් ලෙස පමණක් දිස් වේ.
සාමාන්ය වැරදි
- වෙනම statuses field එකක් සෙවීම. Statuses පැමිණෙන්නේ messages මත ය, එබැවින් value.messages පමණක් කියවන handler එකක් කිසිදු දෝෂයක් නොමැතිව ඒවා නැති කරයි.
- read ට පෙර delivered අවශ්ය යැයි උපකල්පනය. පණිවිඩය පැමිණි මොහොතේ ම read වන විට Meta delivered webhook එක මඟ හරියි.
- send ප්රතිචාරය බෙදා හැරීම ලෙස සැලකීම. wamid එකක් අර්ථ දක්වන්නේ Meta ඉල්ලීම පිළිගත් බව ය; විනාඩි ගණනකට පසු failed status එකක් පැමිණිය හැක.
- ගනුදෙනුකරුවන් recipient_id පමණක් මත යතුරු කිරීම. BSUID වෙත යැවූ විට සහ දුරකථන අංකය ලබා ගත නොහැකි විට එය ඉවත් කර ඇත; BSUID රැගෙන යන්නේ recipient_user_id ය.
ඔබේ automations, AI හෝ කේතය යවන දේවල statuses ඔබේ server එකට යයි: direct mode හි Meta වෙතින් කෙලින්ම, නැතහොත් automations සක්රිය විට Forward URL එකට යොමු කර X-EC-Signature සමඟ අත්සන් කර, සහ ඒවා පෙරනිමියෙන් ගබඩා නොකෙරේ. US$ 9 සිට US$ 0.75 දක්වා අංකයකට මාසිකව, අංක එකතු කරන තරමට පහත වැටේ, පළමු දින 3 නොමිලේ.
නිතර අසන ප්රශ්න
Status webhooks වල පණිවිඩයේ පෙළ ඇතුළත් ද?
නැත. status එකක wamid, status, ලබන්නා, කාල මුද්රා සහ අදාළ වන විට pricing සහ දෝෂ ඇත. එය පෙන්වීමට අවශ්ය නම්, wamid මගින් යතුරු කරන ලද ඔබ යැවූ දේ පිළිබඳ ඔබේම පිටපත තබා ගන්න.
පසුව Meta වෙතින් පැරණි statuses ලබා ගත හැකි ද?
නොහැක. Meta webhook මාර්ගෝපදේශය පවසන්නේ ඓතිහාසික webhook දත්ත ලබා ගැනීමට APIs නොමැති බව ය, එබැවින් Meta නැවත උත්සහ කිරීම නවතා දැමූ පසු, දින 7 දක්වා, ඔබේ endpoint ග්රහණය නොකළ status එකක් නැති වේ.
biz_opaque_callback_data කුමට ද?
එය ඔබ යවන විට සකසන string එකකි, උදාහරණයක් ලෙස ඔබේම order හෝ ticket id. Meta එය එම පණිවිඩයේ statuses තුළ ආපසු ලබා දෙයි, එවිට wamid පළමුව සෙවීමෙන් තොරව status එක ඔබේ වාර්තාවට ගැලපිය හැක.
Status webhooks 200 සමඟ පිළිතුරු දිය යුතු ද?
ඔව්, ඕනෑම webhook POST එකක් මෙන්. Meta වෙනත් ඕනෑම ප්රතිචාරයක් අසාර්ථක බෙදා හැරීමක් ලෙස සලකා නැවත යවයි, එය එකම status දෙවරක් ඔබ වෙත පැමිණීමේ එක් ක්රමයකි.
තවදුරටත් කියවන්න
ආරම්භ කිරීමට සූදානම්ද?
WhatsApp Coexistence මිනිත්තු කිහිපයකින් සකසන්න, මාස ගණනකින් නොව. යෙදුම දුරකථනයේ දිගටම ක්රියා කරයි.
නොමිලේ trial කාලය ආරම්භ කරන්නසත්යාපනය කළේ