WhatsApp वेबहुक स्टेटस: sent, delivered, read आणि failed
स्टेटस वेबहुक सांगतात की WhatsApp Cloud API द्वारे व्यवसायाने पाठवलेल्या मेसेजचे काय झाले. ते messages फील्डवर येतात, पण messages array ऐवजी statuses array सह: sent (एक खूण), delivered (दोन खुणा), read (दोन निळ्या खुणा), व्हॉइस मेसेजसाठी played, आणि errors array सह failed. statuses[].id ला तुमच्या पाठवण्याच्या विनंतीने परत आलेल्या wamid शी जुळवा.
easyCoexistence तुम्ही आधीच वापरत असलेला WhatsApp Business ॲप नंबर Coexistence द्वारे Meta च्या Cloud API ला जोडते.
Meta पाठवत असलेली स्टेटस मूल्ये: sent, delivered, read, played (व्हॉइस मेसेजचे पहिले प्ले) आणि failed.
एका बाहेर पाठवलेल्या मेसेजमुळे वेगवेगळे स्टेटस वेबहुक येऊ शकतात: sent, delivered आणि read.
या Graph API आवृत्तीपासून conversation ऑब्जेक्ट वगळला जातो, फक्त मोफत एंट्री पॉइंट विंडोमधील मेसेजेस सोडून.
भूतकाळातील वेबहुक डेटा मिळवण्यासाठी एपीआय नाहीत; Meta सांगते की पेलोड्स येताच कॅप्चर करून साठवा.
फॉरवर्ड केलेल्या स्टेटसवरील X-EC-Event हेडर: स्टेटस messages इव्हेंट्समध्ये, value.statuses अंतर्गत पाठवले जातात.
WhatsApp स्टेटस वेबहुक कुठे येतात?
ग्राहक जे पाठवतात तोच messages फील्ड, त्याच ऑब्जेक्ट, entry आणि changes एन्व्हेलपमध्ये. फरक value च्या आत आहे: येणाऱ्या मेसेजमध्ये messages array असतो, स्टेटसमध्ये statuses array असतो. फक्त value.messages वाचणारा हँडलर कोणतीही त्रुटी न दाखवता प्रत्येक स्टेटस गाळून टाकतो. metadata.phone_number_id सांगते की तुमच्यापैकी कोणत्या नंबरने मेसेज पाठवला, आणि ग्राहकाचे प्रोफाइल नाव, wa_id आणि BSUID असलेला contacts array सोबत येतो, फक्त failed स्टेटसवर आणि ग्रुप मेसेजच्या sent स्टेटसवर वगळता. हे Meta च्या सर्व्हरवरून निघालेल्या मार्केटिंग टेम्प्लेटचे 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"
}
]
}
]
}प्रत्येक स्टेटस मूल्याचा अर्थ काय?
प्रत्येक मूल्य WhatsApp मध्ये ग्राहकाला दिसणाऱ्या खुणेशी जुळते. स्टेटस read तेव्हाच मानले जाते जेव्हा ते आधी delivered झालेले असते; पण चॅट आधीच उघडे असताना ग्राहकाला मेसेज मिळाला, तर Meta अंतर्गत ऑप्टिमायझेशन म्हणून delivered वेबहुकशिवाय थेट read पाठवते. म्हणून ट्रॅकरने delivered आलेच नाही तरीही read स्वीकारले पाहिजे, आणि स्टेटस एका ठराविक क्रमाने एकामागोमाग येतील अशी अपेक्षा न ठेवता त्यांना क्रमवारी लावली पाहिजे.
स्टेटस ऑब्जेक्टमध्ये कोणते फील्ड असतात?
मेसेजपेक्षा कमी, आणि अनेक फील्ड अटींवर अवलंबून असतात. प्रत्येक फील्ड कधी असते ते Meta च्या संदर्भात दिलेले आहे:
- id: तुम्ही पाठवलेल्या मेसेजचा wamid, जुळवण्याची मुख्य किल्ली.
- status आणि timestamp: मूल्य आणि वेबहुक ट्रिगर झालेली Unix वेळ, स्ट्रिंग म्हणून.
recipient_id: फोन नंबर किंवा ग्रुप id; तुम्ही BSUID वर पाठवले आणि नंबर उपलब्ध नसेल तेव्हा वगळला जातो.recipient_user_id: ग्राहकाचा BSUID; फोन नंबरवर पाठवले असताना failed स्टेटसवर वगळला जातो.recipient_typeआणिrecipient_participant_id: फक्त ग्रुपला पाठवलेल्या मेसेजसाठी.biz_opaque_callback_data: फक्त तेव्हा जेव्हा तुम्ही ते पाठवण्याच्या विनंतीत सेट केले असेल.- pricing: फक्त sent वर आणि delivered किंवा read यांपैकी एकावर. errors: फक्त failed वर.
स्टेटस तुम्ही पाठवलेल्या मेसेजशी कसे जुळवायचे?
wamid द्वारे. पाठवण्याच्या विनंतीला messages[0].id सह उत्तर मिळते, आणि त्या मेसेजच्या प्रत्येक स्टेटसमध्ये statuses[].id मध्ये तीच मूल्य असते. पाठवताना ती तुमच्या स्वतःच्या रेकॉर्डसोबत साठवा, मग स्टेटस आल्यावर रेकॉर्ड अपडेट करा आणि गाठलेला सर्वोच्च स्टेटस ठेवा, म्हणजे उशिरा आलेले delivered read वर लिहिले जाणार नाही. ज्या स्टेटसचा wamid तुम्हाला माहीत नाही, तो नंबरवरील दुसऱ्या कशाने तरी पाठवला गेला असतो, उदाहरणार्थ ऑटोमेशनने, आणि त्याकडे दुर्लक्ष करता येते किंवा लॉग करता येतो.
// 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 नंबरवर काय बदलते?
स्टेटस एपीआय द्वारे काय पाठवले गेले ते दर्शवतात: तुमच्या ऑटोमेशनमधील उत्तरे, MCP कनेक्टरद्वारे तुमच्या AI ने पाठवलेले मेसेज आणि तुमच्या स्वतःच्या कोडने पाठवलेले काहीही. मालक WhatsApp Business ॲपमध्ये जे टाइप करतो ते smb_message_echoes म्हणून वेगळ्या पद्धतीने सॉफ्टवेअरपर्यंत पोहोचते; Meta याचे ॲपने पाठवलेल्या मेसेजचे आरसा म्हणून दस्तऐवजीकरण करते. एकदाच होणाऱ्या हिस्ट्री इम्पोर्टमध्ये आलेल्या मेसेजचे स्वतःचे स्टेटस हिस्ट्री वेबहुकच्या आत असते, delivered, read, played, pending आणि error अशा मूल्यांसह.
स्टेटस नंबरचे messages फील्ड जिथे जाते तिथे जातात. थेट डेस्टिनेशनसह, Meta ती थेट तुमच्या एंडपॉइंटवर पाठवते, कारण messages हे असे फील्ड आहे जे Meta डेस्टिनेशनला ओव्हरराइड करू देते. ऑटोमेशन चालू असेल आणि Forward URL सेट असेल तर ते त्या URL वर messages इव्हेंट्स म्हणून पोहोचतात.
तुमच्या AI किंवा ऑटोमेशनला मेसेज पोहोचला हे कसे कळते?
पाठवण्याच्या कृतीद्वारे नाही, तर तुमच्या डेस्टिनेशनद्वारे. जेव्हा असिस्टंट send_template किंवा send_message कॉल करतो, तेव्हा टूलच्या निकालात wamid असतो आणि Meta ने मेसेज स्वीकारल्याचे सांगितले जाते; डिलिव्हरीची पुष्टी नंतर ग्राहकाच्या डिव्हाइसवर होते आणि स्टेटस म्हणून कळवली जाते. easyCoexistence कडे चौकशी करण्यासाठी स्टेटसचा इतिहास ठेवलेला नाही, आणि कोणताही MCP टूल स्टेटस वाचत नाही, म्हणून डिलिव्हरीची पुष्टी हवी असलेल्या एजंटने तुमच्या सिस्टीममधून पाठवावे किंवा तुमच्या Forward URL वर येणारे स्टेटस वाचावेत.
ऑटोमेशनलाही हेच लागू होते: Runs टॅबमधील रन Meta ने मेसेज स्वीकारल्यानंतर उत्तराचा टप्पा पूर्ण झालेला दाखवतो, आणि नंतर कळवलेली अपयश फक्त तुमच्या डेस्टिनेशनवर failed स्टेटस म्हणून दिसते.
सामान्य चुका
- वेगळा statuses फील्ड शोधणे. स्टेटस messages वर येतात, त्यामुळे फक्त value.messages वाचणारा हँडलर त्यांना कोणतीही त्रुटी न दाखवता गमावतो.
- read च्या आधी delivered ची अट ठेवणे. मेसेज येताक्षणीच वाचला गेला तर Meta delivered वेबहुक वगळते.
- पाठवण्याच्या प्रतिसादाला डिलिव्हरी समजणे. wamid म्हणजे Meta ने विनंती स्वीकारली आहे; अपयश काही मिनिटांनंतर failed स्टेटस म्हणून येऊ शकते.
- ग्राहकांना फक्त recipient_id वरून ओळखणे. BSUID वर पाठवले आणि फोन नंबर उपलब्ध नसेल तेव्हा ते वगळले जाते; BSUID recipient_user_id मध्ये असतो.
तुमचे ऑटोमेशन, तुमचा AI किंवा तुमचा कोड जे पाठवतात त्याचे स्टेटस तुमच्या सर्व्हरवर जातात: direct मोडमध्ये थेट Meta कडून, किंवा ऑटोमेशन चालू असताना तुमच्या Forward URL वर फॉरवर्ड होऊन X-EC-Signature सह सही केलेले, आणि ते डीफॉल्टनुसार साठवले जात नाहीत. US$ 9 पासून US$ 0.75 पर्यंत प्रति नंबर प्रति महिना, नंबर जोडल्यावर कमी होत जाते, पहिले 3 दिवस मोफत.
वारंवार विचारले जाणारे प्रश्न
स्टेटस वेबहुकमध्ये मेसेजचा मजकूर असतो का?
नाही. स्टेटसमध्ये wamid, स्टेटस, प्राप्तकर्ता, टाइमस्टॅम्प आणि लागू तेथे pricing व errors असतात. स्टेटससोबत दाखवायचे असल्यास, पाठवलेल्या मेसेजची स्वतःची प्रत wamid च्या किल्लीने साठवा.
नंतर Meta कडून जुने स्टेटस मिळवता येतात का?
नाही. Meta च्या वेबहुक मार्गदर्शकात म्हटले आहे की ऐतिहासिक वेबहुक डेटा मिळवण्यासाठी एपीआय नाहीत, म्हणून तुमच्या एंडपॉइंटने कॅप्चर न केलेले स्टेटस, Meta retry थांबवल्यानंतर, म्हणजे जास्तीत जास्त 7 दिवसांनी, कायमचे हरवते.
biz_opaque_callback_data कशासाठी आहे?
पाठवताना तुम्ही सेट करता ती स्ट्रिंग आहे, जसे तुमचा स्वतःचा ऑर्डर किंवा तिकीट id. Meta ते त्या मेसेजच्या statuses मध्ये परत करते, म्हणजे आधी wamid शोधल्याशिवाय स्टेटस तुमच्या रेकॉर्डशी जुळवता येते.
स्टेटस वेबहुकला 200 ने उत्तर देणे आवश्यक आहे का?
होय, इतर कोणत्याही वेबहुक POST प्रमाणे. Meta इतर कोणताही प्रतिसाद अयशस्वी डिलिव्हरी मानते आणि त्याची पुन्हा पाठवणी करते; त्यामुळेच एकच स्टेटस दोनदा येण्याचा एक मार्ग तयार होतो.
पुढे वाचा
सुरुवात करण्यासाठी तयार आहात?
WhatsApp Coexistence काही मिनिटांत सेट करा, काही महिन्यांत नाही. ॲप फोनवर काम करत राहते.
मोफत ट्रायल सुरू करापडताळले: