WhatsApp वेबहुक स्टेटस: भेजा गया, डिलीवर हुआ, पढ़ा गया और विफल
स्टेटस वेबहुक बताते हैं कि WhatsApp Cloud API के ज़रिए कारोबार द्वारा भेजे गए मैसेज के साथ क्या हुआ। ये messages फ़ील्ड पर आते हैं, जिसमें messages एरे की जगह statuses एरे होता है: sent (एक टिक), delivered (दो टिक), read (दो नीले टिक), वॉइस मैसेज के लिए played, और errors एरे के साथ 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 एरे होता है, स्टेटस में statuses एरे। जो हैंडलर केवल value.messages पढ़ता है, वह बिना किसी गड़बड़ी के हर स्टेटस गिरा देगा। metadata.phone_number_id बताता है कि आपके किस नंबर से मैसेज गया, और contacts एरे आता है जिसमें ग्राहक का प्रोफ़ाइल नाम, wa_id और BSUID होता है। अपवाद: 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 भेजता है। इसलिए ट्रैकर को read स्वीकार करना चाहिए भले ही delivered न आया हो, और स्टेटस को एक तय क्रम में एक-एक करके उम्मीद करने के बजाय उनका रैंक तय करना चाहिए।
स्टेटस ऑब्जेक्ट में कौन-से फ़ील्ड होते हैं?
मैसेज से कम, और कई शर्तों पर निर्भर। Meta का रेफ़रेंस बताता है कि हर फ़ील्ड कब मौजूद होता है:
- id: वह wamid जो आपने भेजा, मिलान की कुंजी।
- status और timestamp: मान और वह Unix समय जब वेबहुक ट्रिगर हुआ, स्ट्रिंग के रूप में।
recipient_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 यूआरएल सेट हो, तो वे messages इवेंट के रूप में उस यूआरएल पर पहुँचते हैं।
आपका AI या ऑटोमेशन कैसे जानता है कि मैसेज डिलीवर हुआ?
सेंड के ज़रिए नहीं, बल्कि आपके डेस्टिनेशन के ज़रिए। जब कोई असिस्टेंट send_template या send_message कॉल करता है, तो टूल का नतीजा wamid लेकर आता है और कहता है कि Meta ने मैसेज स्वीकार कर लिया; डिलीवरी बाद में, ग्राहक के डिवाइस पर, पुष्टि होती है और स्टेटस के रूप में रिपोर्ट होती है। easyCoexistence के पास क्वेरी करने के लिए कोई स्टेटस हिस्ट्री नहीं है, और कोई MCP टूल स्टेटस नहीं पढ़ता, इसलिए जिस एजेंट को डिलीवरी की पुष्टि चाहिए, उसे अपने सिस्टम से भेजना चाहिए या उस Forward यूआरएल के स्टेटस पढ़ने चाहिए जो आपको मिलते हैं।
ऑटोमेशन पर भी यही लागू होता है: Runs टैब में चलने वाला रन दिखाता है कि जवाब वाला स्टेप पूरा हुआ जब Meta ने मैसेज स्वीकार किया, और बाद में रिपोर्ट हुई विफलता केवल आपके डेस्टिनेशन पर failed स्टेटस के रूप में दिखती है।
आम गड़बड़ियाँ
- एक अलग statuses फ़ील्ड की तलाश। स्टेटस messages पर आते हैं, इसलिए जो हैंडलर केवल value.messages पढ़ता है, वह उन्हें बिना किसी गड़बड़ी के खो देता है।
- delivered को read से पहले माँगना। जब मैसेज आते ही पढ़ लिया जाता है, तो Meta delivered वेबहुक छोड़ देता है।
- सेंड के जवाब को डिलीवरी मान लेना। wamid का मतलब है कि Meta ने अनुरोध स्वीकार किया; विफलता मिनटों बाद failed स्टेटस के रूप में आ सकती है।
- ग्राहकों की पहचान केवल recipient_id से करना। यह तब नहीं होता जब आपने BSUID पर भेजा हो और फ़ोन नंबर उपलब्ध न हो; BSUID recipient_user_id में होता है।
आपके ऑटोमेशन, AI या कोड के भेजे मैसेज के स्टेटस आपके सर्वर पर जाते हैं: डायरेक्ट मोड में सीधे Meta से, या ऑटोमेशन चालू होने पर आपके Forward यूआरएल पर भेजे जाते हैं, X-EC-Signature के साथ साइन करके, और डिफ़ॉल्ट रूप से स्टोर नहीं होते। US$ 9 से US$ 0.75 तक प्रति नंबर प्रति माह, जैसे-जैसे नंबर जोड़ते हैं वैसे घटता है, पहले 3 दिन फ़्री।
अक्सर पूछे जाने वाले सवाल
क्या स्टेटस वेबहुक में मैसेज का टेक्स्ट होता है?
नहीं। स्टेटस में wamid, स्टेटस, प्राप्तकर्ता, टाइमस्टैम्प और, जहाँ लागू हो, pricing और errors होते हैं। अगर आपको स्टेटस के साथ उसे दिखाना है, तो wamid से कुंजीबद्ध, भेजे गए मैसेज की अपनी प्रति रखें।
क्या बाद में Meta से पिछले स्टेटस ला सकते हैं?
नहीं। Meta की वेबहुक गाइड कहती है कि ऐतिहासिक वेबहुक डेटा लाने के लिए कोई एपीआई नहीं है, इसलिए जो स्टेटस आपका एंडपॉइंट कैप्चर नहीं कर पाया, वह Meta के रीट्राई बंद करने के बाद चला जाता है, जो 7 दिन तक हो सकता है।
biz_opaque_callback_data किसलिए है?
यह एक स्ट्रिंग है जिसे आप भेजते समय सेट करते हैं, जैसे आपकी अपनी ऑर्डर या टिकट आईडी। Meta इसे उस मैसेज के statuses में लौटाता है, ताकि आप पहले wamid खोजे बिना स्टेटस को अपने रिकॉर्ड से मिला सकें।
क्या स्टेटस वेबहुक का जवाब 200 से देना ज़रूरी है?
हाँ, किसी भी वेबहुक POST की तरह। Meta किसी भी दूसरे जवाब को विफल डिलीवरी मानता है और उसे दोबारा भेजता है, और यही एक तरीका है जिससे वही स्टेटस आपके पास दो बार पहुँचता है।
पढ़ना जारी रखें
शुरू करने के लिए तैयार हैं?
WhatsApp Coexistence को महीनों में नहीं, मिनटों में कॉन्फ़िगर करें। ऐप्लिकेशन मोबाइल पर काम करता रहता है।
मुफ़्त ट्रायल शुरू करेंइस तारीख को सत्यापित