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 object हटाइन्छ, निःशुल्क प्रवेश बिन्दु विन्डोमा रहेका म्यासेज बाहेक।
विगतको वेबहुक डेटा ल्याउने API छैनन्; Meta ले पेलोड आउनासाथ सुरक्षित गरेर भण्डारण गर्न भन्छ।
फर्वार्ड गरिएको स्ट्याटसमा X-EC-Event हेडर: statuses messages इभेन्टभित्र value.statuses अन्तर्गत आउँछन्।
WhatsApp स्ट्याटस वेबहुक कहाँ आउँछन्?
उही messages फिल्डमा, जसमा ग्राहकले पठाएका म्यासेज आउँछन्, उही object, entry र changes संरचनामा। भिन्नता value भित्र छ: आउने म्यासेजमा messages array हुन्छ, स्ट्याटसमा statuses array। जसले value.messages मात्र पढ्छ, त्यसले हरेक स्ट्याटस कुनै त्रुटि बिना छोड्छ। metadata.phone_number_id ले कुन नम्बरले म्यासेज पठायो भन्छ, र ग्राहकको प्रोफाइल नाम, wa_id र BSUID भएको contacts array पनि आउँछ, तर failed स्ट्याटस र समूह म्यासेजको sent स्ट्याटसमा बाहेक। यो Meta को उदाहरण हो, marketing टेम्प्लेट जो 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 स्वीकार गर्नुपर्छ, र स्ट्याटसहरूलाई निश्चित क्रममा एक-एक गरी खोज्नुको सट्टा मूल्यांकन गर्नुपर्छ।
स्ट्याटस object मा कुन फिल्डहरू हुन्छन्?
म्यासेजभन्दा कम फिल्ड हुन्छन्, र धेरैजसो सर्तमा आधारित हुन्छन्। 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 नम्बरमा के फरक पर्छ?
स्ट्याटसहरूले API मार्फत पठाइएको कुरा वर्णन गर्छन्: तपाईंका अटोमेसनका उत्तर, तपाईंको AI ले MCP कनेक्टरमार्फत पठाएका म्यासेज, र तपाईंको आफ्नै कोडले पठाएको कुरा। व्यवसायको मालिकले WhatsApp Business एपमा टाइप गरेका कुरा फरक तरिकाले सफ्टवेयरसम्म पुग्छन्, smb_message_echoes को रूपमा, जसलाई Meta ले एपबाट पठाइएका म्यासेजको मिरर भनेर कागजातमा लेखेको छ। एक पटकको इतिहास आयातमा आएका म्यासेजहरूको आफ्नै स्ट्याटस history वेबहुकभित्र हुन्छ, delivered, read, played, pending र error जस्ता मानसहित।
स्ट्याटसहरू नम्बरको messages फिल्ड जहाँ जान्छ त्यहीँ जान्छन्। Direct गन्तव्यमा, Meta ले सिधै तपाईंको endpoint मा पठाउँछ, किनभने messages लाई Meta ले गन्तव्यले ओभरराइड गर्न दिन्छ। अटोमेसन खुला छ र Forward URL सेट छ भने, तिनीहरू messages इभेन्टका रूपमा त्यो URL मा पुग्छन्।
तपाईंको AI वा अटोमेसनले म्यासेज पुग्यो कि भनी कसरी थाहा पाउँछ?
पठाउने बेलामा होइन, तपाईंको गन्तव्यमार्फत। AI ले send_template वा send_message कल गर्दा, टूलको नतिजामा wamid हुन्छ र Meta ले म्यासेज स्वीकार गरेको भनिन्छ; डेलिभरी ग्राहकको उपकरणमा पछि पुष्टि हुन्छ र स्ट्याटसका रूपमा रिपोर्ट गरिन्छ। easyCoexistence ले क्वेरी गर्न मिल्ने स्ट्याटस इतिहास राख्दैन, र कुनै MCP टूलले स्ट्याटस पढ्दैन। त्यसैले डेलिभरी पुष्टि चाहिने एजेन्टले तपाईंको प्रणालीमार्फत पठाउनुपर्छ, वा Forward URL ले पाउने स्ट्याटस पढ्नुपर्छ।
अटोमेसनका लागि पनि यही हो: Runs ट्याबमा रहेको रनले Meta ले म्यासेज स्वीकार गरेपछि reply चरण done देखाउँछ, र पछि रिपोर्ट गरिएको असफलता तपाईंको गन्तव्यमा failed स्ट्याटसका रूपमा मात्र देखिन्छ।
सामान्य गल्तीहरू
- स्ट्याटसका लागि छुट्टै statuses फिल्ड खोज्नु। स्ट्याटस messages मा आउँछन्, त्यसैले जसले value.messages मात्र पढ्छ, उसले तिनलाई कुनै त्रुटि बिना गुमाउँछ।
- read भन्दा अघि delivered अनिवार्य मान्नु। म्यासेज आउने बित्तिकै पढिएको भए Meta ले delivered वेबहुक छोड्छ।
- पठाउने प्रतिक्रियालाई डेलिभरी मान्नु। wamid को अर्थ Meta ले अनुरोध स्वीकार गरेको हो; मिनेटौंपछि failed स्ट्याटस आउन सक्छ।
- recipient_id मात्रलाई ग्राहक पहिचान मान्नु। BSUID मा पठाउँदा र फोन नम्बर उपलब्ध नभएमा त्यो हटाइन्छ; recipient_user_id मा BSUID हुन्छ।
तपाईंका अटोमेसन, AI वा कोडले पठाएका कुराका स्ट्याटस direct मोडमा Meta बाट सिधै तपाईंको सर्भरमा जान्छन्, वा अटोमेसन खुला भएमा Forward URL मा X-EC-Signature सहित हस्ताक्षर गरेर पठाइन्छन्, र डिफल्टमा भण्डारण गरिँदैनन्। प्रति नम्बर प्रति महिना US$ 9 देखि US$ 0.75 सम्म, नम्बर थप्दै जाँदा घट्दै, पहिलो 3 दिन निःशुल्क।
बारम्बार सोधिने प्रश्नहरू
स्ट्याटस वेबहुकमा म्यासेजको पाठ हुन्छ?
हुँदैन। स्ट्याटसमा wamid, status, recipient, timestamp र लागू हुने ठाउँमा pricing र त्रुटिहरू हुन्छन्। देखाउनु परे पठाएको कुराको आफ्नै प्रति wamid सँग राख्नुहोस्।
पछि Meta बाट विगतका स्ट्याटस तान्न सकिन्छ?
सकिँदैन। Meta को वेबहुक गाइडले भन्छ विगतको वेबहुक डेटा ल्याउने API छैनन्, त्यसैले Meta ले पुनःप्रयास रोकेपछि, 7 दिनसम्म, तपाईंको endpoint ले नसमातेको स्ट्याटस हराउँछ।
biz_opaque_callback_data किन हो?
यो पठाउँदा सेट गर्ने स्ट्रिङ हो, जस्तै आफ्नै अर्डर वा टिकट id। Meta ले त्यो म्यासेजको statuses मा फिर्ता पठाउँछ, त्यसैले wamid पहिले खोज्नु नपरी स्ट्याटसलाई आफ्नो रेकर्डसँग मिलाउन सकिन्छ।
स्ट्याटस वेबहुकको जवाफ 200 दिनुपर्छ?
हो, जुनसुकै वेबहुक POST जस्तै। Meta ले अरू कुनै प्रतिक्रियालाई असफल डेलिभरी मान्छ र पुनःप्रयास गर्छ, जुन एउटै स्ट्याटस दुईपटक आउनुको एउटा कारण हो।
पढ्दै जानुहोस्
सुरु गर्न तयार हुनुहुन्छ?
महिनौं होइन, केही मिनेटमै WhatsApp Coexistence सेट अप गर्नुहोस्। एप फोनमा चलिरहन्छ।
निःशुल्क ट्रायल सुरु गर्नुहोस्प्रमाणीकरण गरिएको