सामग्री पर जाएँ
37 min read

Meta Graph API से कनेक्ट करना

मौजूदा WhatsApp Cloud API इंटीग्रेशन को दोबारा लिखे बिना WizMessage पर पॉइंट करें — Meta के पाथ, Meta की रिक्वेस्ट बॉडीज़, Meta का एरर एनवेलप, Meta के अपने फ़ॉर्मेट में वेबहुक्स, और टेम्पलेट्स, बिज़नेस प्रोफ़ाइल, QR कोड और फ़्लो के लिए अकाउंट-मैनेजमेंट एंडपॉइंट्स।

Meta Graph API से कनेक्ट करना

WizMessage के ज़रिए WhatsApp मैसेज भेजने के दो तरीक़े हैं। अगर आप बिल्कुल शुरुआत से शुरू कर रहे हैं, तो WizMessage API आपके काम की चीज़ है — यह आपको नाम वाले टेम्पलेट वैरिएबल्स, एक मैपिंग UI, और एक reference फ़ील्ड देता है जिसके आधार पर आप अपने रिकॉर्ड्स को लिंक कर सकते हैं।

यह पेज दूसरे तरीक़े का विवरण देता है। यह Meta के WhatsApp Cloud API से इतनी बारीकी से मेल खाता है कि Meta के लिए पहले से लिखा गया कोड सिर्फ़ दो चीज़ें बदलने के बाद यहाँ काम करता है: बेस URL और टोकन। वही पाथ, वही रिक्वेस्ट बॉडीज़, वही रिस्पॉन्स बॉडीज़, वही एरर एनवेलप। अगर आपके पास कोई मौजूदा इंटीग्रेशन है, कोई लाइब्रेरी है, या कोई ऐसा डेवलपर है जो Cloud API को पहले से जानता है, तो यह छोटा रास्ता है।

यह सिर्फ़ भेजने का इंटरफ़ेस नहीं है। मैसेजिंग के साथ-साथ इसमें अकाउंट-मैनेजमेंट एंडपॉइंट्स भी शामिल हैं — टेम्पलेट्स बनाना और हटाना, बिज़नेस प्रोफ़ाइल पढ़ना और दोबारा लिखना, QR कोड, कॉमर्स सेटिंग्स, ब्लॉक लिस्ट, फ़ोन सेटिंग्स और फ़्लो — यह सब Meta के अपने पाथ पर। अकाउंट प्रबंधित करना इसकी पूरी सूची है, और यहाँ क्या उपलब्ध नहीं है उतना ही महत्वपूर्ण दूसरा हिस्सा है।

दोनों इंटरफ़ेस एक ही API कीज़, वही अनुमतियाँ और वही रेट लिमिट्स इस्तेमाल करते हैं। कुछ भी डेप्रिकेट नहीं किया गया है — प्रत्येक इंटीग्रेशन के हिसाब से चुनें, और आप दोनों का एक साथ भी उपयोग कर सकते हैं।

आपको कौन-सा चाहिए

WizMessage API और Meta Graph-कम्पैटिबल API की तुलनावह चुनें जो आपके पास पहले से मौजूद सिस्टम से मेल खाता होWizMessage API/api/v1/externalनाम वाले टेम्पलेट वैरिएबल्सडैशबोर्ड में मैपिंग UIreference फ़ील्ड, स्टेटस लुकअपहमारा अपना JSON एनवेलपनए सिरे से शुरुआत करने के लिए सबसे अच्छाMeta Graph API/v26.0/{phone-number-id}/…Meta की रिक्वेस्ट बॉडीज़Meta का एरर एनवेलपटेम्पलेट्स और प्रोफ़ाइल प्रबंधित करेंMeta के फ़ॉर्मेट में वेबहुक्सजब आपके पास Cloud API कोड हो तो सबसे अच्छावही कीज़, वही अनुमतियाँ, वही रेट लिमिट्स। आप चाहें तो दोनों का उपयोग कर सकते हैं।
दो इंटरफ़ेस, एक अकाउंट। दोनों में से कोई भी बंद नहीं हो रहा।

बुनियादी बातें

बेस URL, और पाथ में वर्ज़न

https://wizmessage.com/v26.0/{phone-number-id}/messages

वर्ज़न सेगमेंट वास्तविक और अनिवार्य है, लेकिन इसकी वैल्यू से कुछ नहीं बदलता। हम इसे v{major}.{minor} के रूप में मैच करते हैं और फिर अनदेखा कर देते हैं — प्लेटफ़ॉर्म यह तय करता है कि वह अपस्ट्रीम में किस Graph वर्ज़न से बात करता है।

जानने लायक दो बातें:

  • किसी पुराने वर्ज़न को पिन करके रखना काम करता रहता है। जब Meta उस वर्ज़न को रिटायर कर देता है जिसे आपके कोड में हार्डकोड किया गया है, तब भी यहाँ की जाने वाली कॉल्स जारी रहती हैं। कुछ भी शेड्यूल करने की ज़रूरत नहीं है।
  • अकेला v26 अस्वीकार कर दिया जाता है। माइनर नंबर वैकल्पिक नहीं है। v26.0 ठीक है, v26 404 है।

{phone-number-id} वही WhatsApp नंबर होना चाहिए जो आपके द्वारा उपयोग की जा रही API key के पीछे है। इसके अलावा किसी भी अन्य को अस्वीकार कर दिया जाता है — देखें जब कोई id आपकी न हो।

ऑथेंटिकेशन

अपनी API key को bearer टोकन के रूप में भेजें, ठीक वैसे ही जैसे आप Meta को एक्सेस टोकन भेजते हैं।

हेडरवैल्यू
AuthorizationBearer pk_live_… — आपकी पूरी API key, न कि डैशबोर्ड में दिखाया गया प्रीफ़िक्स।

यहाँ X-API-Key भी स्वीकार की जाती है, इसलिए WizMessage API के साथ पहले से काम कर रही key में किसी हेडर बदलाव की आवश्यकता नहीं होती। Bearer प्राथमिकता देने योग्य रूप है: यह वही है जो एक अनमॉडिफ़ाइड Meta SDK भेजता है, और यही इस सरफ़ेस का मुख्य मक़सद है।

नोट: key पर "Require signature" बंद (off) होना चाहिए। यह यहाँ कोई ऐच्छिक विकल्प नहीं है। इसे सक्षम (enabled) रखने वाली key Meta Graph वेबहुक को सेव नहीं कर सकती — डैशबोर्ड "Signed-request enforcement is not compatible with the Graph format — disable it on this key first" कहकर मना कर देता है — और इस सरफ़ेस पर इसके द्वारा की जाने वाली हर अनसाइंड कॉल 401 के साथ code 190 के रूप में अस्वीकार कर दी जाती है। कोई सामान्य Cloud API क्लाइंट हमारा रिक्वेस्ट सिग्नेचर जनरेट नहीं कर सकता, इसलिए डिज़ाइन के अनुसार ये दोनों एक साथ संभव नहीं हैं।

आपकी सदस्यता

API मॉड्यूल के लिए एक सक्रिय Wiz Bot या Wiz Pro सदस्यता ज़रूरी है। यह दोनों सरफ़ेस पर लागू होता है — WizMessage API और यह वाली — और इसकी जाँच हर कॉल पर की जाती है, न कि केवल तब जब key बनाई जाती है।

यदि सदस्यता समाप्त हो जाती है, तो API उसी क्षण बंद नहीं होता। समाप्ति के बाद की पहली कॉल सात दिनों की विंडो शुरू करती है और उसे आगे जाने दिया जाता है, और उस विंडो के दौरान हर रिस्पॉन्स में एक हेडर होता है:

हेडरवैल्यू
X-Subscription-WarningSubscription inactive. API access ends in 5 day(s).

विंडो समाप्त होने के बाद, 403 पर Graph code 10 के साथ कॉल्स अस्वीकार कर दी जाती हैं:

{
	"error": {
		"message": "(#10) Access denied. The API module requires an active Wiz Bot or Wiz Pro subscription. Renew at /subscriptions to restore access.",
		"type": "OAuthException",
		"code": 10,
		"fbtrace_id": "AKnBaXsYl7FlmMVw3ql5Ywo"
	}
}
सदस्यता समाप्त होने के बाद API एक्सेस का क्या होता हैएक API keyसामान्यकोई हेडर नहींग्रेस विंडो7 दिन, कॉल्स अब भी सफल होती हैंहर रिस्पॉन्स पर X-Subscription-Warningअस्वीकृत403 पर code 10समाप्ति के बाद पहली कॉलघड़ी यहाँ से शुरू होती हैविंडो समाप्तआगे कोई चेतावनी नहींकिसी भी समय रिन्यू करने पर कुछ ही मिनटों में एक्सेस बहाल हो जाता है।
सदस्यता समाप्त होने से अपने आप कुछ नहीं बदलता। घड़ी आपकी अगली कॉल से शुरू होती है।

तीन बातें जो यह तय करती हैं कि आपको समय रहते पता चलता है या नहीं:

  • घड़ी आपकी पहली कॉल से शुरू होती है, बिलिंग की तारीख़ से नहीं। समाप्ति के बाद दो हफ़्ते तक निष्क्रिय रहने वाली key को भी अपने पूरे सात दिन मिलते हैं, जो तब शुरू होते हैं जब वह अगली बार कॉल करती है।
  • विंडो प्रति API key होती है, प्रति अकाउंट नहीं। हर key अपनी पहली कॉल से अपनी घड़ी खुद चलाती है, इसलिए जिस key से आप टेस्टिंग करते हैं और जो key प्रोडक्शन चला रही है, वे अलग-अलग दिनों में समाप्त होंगी। उस key पर हेडर देखें जो मायने रखती है।
  • अस्वीकृति उस रिक्वेस्ट पर बिना किसी चेतावनी के आती है जो इसे ट्रिगर करती है। X-Subscription-Warning ही एकमात्र अग्रिम सूचना है — इसे लॉग करें, वरना आपको सबसे पहले 403 का ही पता चलेगा।

नोट: रिन्यू करने पर असर दिखने में कुछ मिनट लगते हैं, सेकंड नहीं। एंटाइटेलमेंट का जवाब पाँच मिनट के लिए कैश रहता है और उसके पीछे का सदस्यता स्टेटस अन्य पाँच मिनट के लिए, इसलिए किसी इंटीग्रेशन के फ़ेल होने के दौरान किया गया रिन्यूअल ठीक अगली री-ट्राई पर ठीक नहीं होगा। यह निष्कर्ष निकालने से पहले कि इसने काम नहीं किया, कुछ मिनट इंतज़ार करें।

मैसेज भेजना

Meta की बॉडी के साथ POST /{version}/{phone-number-id}/messages। हम यह जाँचने के अलावा कि यह एक WhatsApp मैसेज है, इसे वैलिडेट नहीं करते — एक मान्य मैसेज कैसा दिखता है, इस पर Meta ही अंतिम प्राधिकारी है, और उसकी एरर किसी भी ऐसी एरर से बेहतर हैं जो हम बना सकते हैं।

POST https://wizmessage.com/v26.0/106540352242922/messages

{
	"messaging_product": "whatsapp",
	"recipient_type": "individual",
	"to": "919876543210",
	"type": "text",
	"text": { "preview_url": false, "body": "Your order has shipped." }
}

नोट: यहाँ to में केवल अंक आते हैं — 919876543210, बिना + के। यह Meta का फ़ॉर्मेट है, और दोनों सरफ़ेस के बीच स्विच करते समय यह सबसे आम ग़लती है: WizMessage API के लिए +E.164 ज़रूरी है और यह इसके अलावा किसी भी अन्य चीज़ को अस्वीकार कर देता है, जबकि यह सरफ़ेस आपकी वैल्यू को सीधे Meta को भेज देता है। एकमात्र अपवाद POST /messages/contacts है, जो दोनों में से कोई भी रूप स्वीकार करता है ताकि Graph बॉडी बिना किसी बदलाव के पोर्ट हो सके।

टेम्पलेट भेजना भी Meta के ही फ़ॉर्मेट में होता है — पोज़िशनल कंपोनेंट्स, न कि नेम्ड वैरिएबल्स। इस सरफ़ेस पर कोई मैपिंग लेयर नहीं है, जो कि कम्पैटिबिलिटी के बदले किया जाने वाला समझौता है।

{
	"messaging_product": "whatsapp",
	"to": "919876543210",
	"type": "template",
	"template": {
		"name": "payment_failed_alert",
		"language": { "code": "en" },
		"components": [
			{
				"type": "body",
				"parameters": [
					{ "type": "text", "text": "Priya Sharma" },
					{ "type": "text", "text": "12 Aug 2026" },
					{ "type": "text", "text": "Wiz Pro" }
				]
			}
		]
	}
}

कॉन्टैक्ट कार्ड भेजना

type: "contacts" एक vCard है — एक नाम, और जो कुछ भी आप इसके साथ जोड़ते हैं। यह हमेशा से इस सरफ़ेस पर काम करता आया है और अब भी करता है, Meta की बॉडी में बिना किसी बदलाव के।

POST https://wizmessage.com/v26.0/106540352242922/messages

{
	"messaging_product": "whatsapp",
	"recipient_type": "individual",
	"to": "919876543210",
	"type": "contacts",
	"contacts": [
		{
			"name": {
				"formatted_name": "Priya Sharma",
				"first_name": "Priya",
				"last_name": "Sharma"
			},
			"phones": [
				{ "phone": "+911122334455", "type": "WORK", "wa_id": "911122334455" }
			],
			"emails": [
				{ "email": "[email protected]", "type": "WORK" }
			],
			"org": { "company": "Acme Retail", "department": "Support", "title": "Account Manager" }
		}
	]
}

name.formatted_name ही एकमात्र फ़ील्ड है जिसकी WhatsApp को आवश्यकता होती है। phones[].wa_id फिर भी जोड़ने लायक है: इसके साथ कार्ड पर एक Message बटन होता है जो उस व्यक्ति के साथ चैट खोलता है, इसके बिना कार्ड को केवल सेव किया जा सकता है।

यही सटीक बॉडी WizMessage API पर POST /messages/contacts पर भी पोस्ट होती है — एनवेलप कीज़, केवल अंकों वाला to और बाकी सब कुछ। यह उस सरफ़ेस पर एकमात्र एंडपॉइंट है जो इस फ़ॉर्मेट को स्वीकार करता है, और यह इसलिए मौजूद है क्योंकि दो चीज़ें जो यह पाथ आपको नहीं दे सकता, वे पाने लायक हैं: यहाँ किया गया सेंड किसी message_id के तहत दर्ज नहीं होता, इसलिए देखने के लिए कोई स्टेटस नहीं होता और मैच करने के लिए कोई message.sent वेबहुक नहीं होता, और Meta तक पहुँचने से पहले बॉडी की शायद ही कोई जाँच होती है। बस URL बदलना ही पूरा माइग्रेशन है।

नोट: एक ही मैसेज में कई कार्ड भेजना Meta का contacts ऐरे है, और Meta इनमें से 257 तक स्वीकार करता है। WizMessage एंडपॉइंट इसे 10 पर सीमित करता है — इसलिए एक बल्क-कार्ड सेंड जो यहाँ काम करता है, उन चुनिंदा बॉडीज़ में से एक है जो बिना किसी बदलाव के पोर्ट नहीं होगी।

किसी मैसेज को पढ़ा हुआ मार्क करना

रीड रिसीट और टाइपिंग इंडिकेटर उसी एंडपॉइंट पर पोस्ट होते हैं, एक ऐसी बॉडी के साथ जिसमें न तो to होता है और न ही type। हर Cloud API SDK का markAsRead() इसके काम करने पर निर्भर करता है, इसलिए यह ठीक वैसे ही समर्थित है जैसा Meta निर्दिष्ट करता है।

POST https://wizmessage.com/v26.0/106540352242922/messages

{
	"messaging_product": "whatsapp",
	"status": "read",
	"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…"
}

जवाब {"success": true} होता है — नीचे दिया गया सेंड एनवेलप नहीं। हर रिस्पॉन्स से messages[0].id पढ़ने की कोशिश करने के बजाय, इस आधार पर ब्रांचिंग करें कि आपने कौन सी कॉल की थी।

वापस क्या मिलता है

Meta का रिस्पॉन्स, बिना किसी बदलाव के:

{
	"messaging_product": "whatsapp",
	"contacts": [{ "input": "919876543210", "wa_id": "919876543210" }],
	"messages": [{ "id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…" }]
}

वह wamid ही मैसेज पर आपका एकमात्र हैंडल है। इस सरफ़ेस में जानबूझकर कोई reference फ़ील्ड और कोई स्टेटस-लुकअप एंडपॉइंट नहीं है — दोनों WizMessage के वे जोड़ हैं जो Meta के API में नहीं हैं, इसलिए उन्हें शामिल करने से वह कम्पैटिबिलिटी टूट जाएगी जिसके लिए यह सरफ़ेस मौजूद है।

किसी मैसेज की स्थिति को ट्रैक करने के लिए, अपने वेबहुक पर आने वाले डिलीवरी स्टेटस के साथ wamid का मिलान करें। यदि आप इसके बजाय पहचान के लिए अपनी खुद की कोई फ़ील्ड चाहते हैं, तो WizMessage API का reference इसी काम के लिए है।

एरर

एरर Meta के एनवेलप में वापस आते हैं, हमारे में कभी नहीं। एरर कहाँ से आया है, इसी से तय होता है कि उसमें से कितना हमारा है।

एरर आप तक कैसे पहुँचता है, यह इस पर निर्भर करता है कि क्या इसे Meta ने जनरेट किया हैइस सरफ़ेस पर कोई एररMeta ने इसे रिजेक्ट कियाहू-ब-हू फ़ॉरवर्ड किया गयाMeta के कोड और सबकोडMeta का अपना fbtrace_idस्टेटस भी Meta का ही होता हैहमने इसे रिजेक्ट कियाऑथ, परमिशन, रेट लिमिटMeta के कोड में लिखा गयाताकि एक ही हैंडलर दोनों को कवर करे401 · 403 · 429 · 400 · 500कभी यह मानकर न चलें कि type सिर्फ़ OAuthException ही होगा — Meta कई तरह के प्रकारों का उपयोग करता है।
Meta के अपने एरर बिना किसी बदलाव के फ़ॉरवर्ड किए जाते हैं। हमारे एरर Meta के कोड उधार लेते हैं।

एरर जो हम रेज़ करते हैं

codeHTTPकब
190401मिसिंग, अज्ञात, रिवोक की गई, सस्पेंड की गई या एक्सपायर्ड की — या ऐसी की पर अनसाइंड कॉल जिसे सिग्नेचर की आवश्यकता है। यह तब भी रेज़ होता है जब WhatsApp अकाउंट का Meta से कनेक्शन टूट गया हो; नीचे दिया गया नोट देखें।
10403की में वह परमिशन नहीं है जिसकी इस कॉल को ज़रूरत है (परमिशन देखें), या अकाउंट की सदस्यता अपनी ग्रेस विंडो पार कर चुकी है।
4429की का प्रति-मिनट या दैनिक कोटा समाप्त हो चुका है।
100400गलत बनावट वाली रिक्वेस्ट (malformed request), पाथ में कोई ऐसा id जो आपका नहीं है, या ऐसा एंडपॉइंट जो इस सरफ़ेस पर उपलब्ध नहीं है।
2500हमारी तरफ़ कुछ विफल हो गया। दोबारा प्रयास करें।

नोट: दो अलग-अलग वजहों से 190 आता है, और उनके समाधान एक-दूसरे के विपरीत हैं। अगर मैसेज में की का ज़िक्र है, तो की को रोटेट करें या दोबारा दर्ज करें। अगर इसमें लिखा है "the connection to this WhatsApp Business Account needs to be renewed", तो की ठीक है और अकाउंट का Meta से लिंक टूट गया है — इसे डैशबोर्ड से दोबारा कनेक्ट करें। दूसरी स्थिति के समाधान के लिए सही काम कर रही की को रोटेट करना सिर्फ़ दोपहर बर्बाद करना है और इससे कुछ नहीं बदलता।

एरर जो Meta रेज़ करता है

जैसे मिले थे वैसे ही हू-ब-हू फ़ॉरवर्ड किए जाते हैं, Meta के HTTP स्टेटस के साथ। Meta द्वारा भेजा गया सब कुछ वैसा ही रहता है — error_subcode, error_data.details, और Meta का अपना fbtrace_id:

{
	"error": {
		"message": "Unsupported post request. Object with ID '106540352242922' does not exist, cannot be loaded due to missing permissions, or does not support this operation.",
		"code": 100,
		"type": "GraphMethodException",
		"error_subcode": 33,
		"fbtrace_id": "AKnBaXsYl7FlmMVw3ql5Ywo"
	}
}

नोट: उस उदाहरण में type पर ध्यान दें — GraphMethodException, न कि OAuthException। Meta कई एक्सेप्शन प्रकारों का उपयोग करता है और हम उन्हें नॉर्मलाइज़ नहीं करते हैं। error.code के आधार पर ब्रांच करें, जो कि एक संख्या है और स्थिर है; type को इंसानों के लिए एक लेबल समझें।

जब कोई id आपका न हो

पाथ में मौजूद हर id — फ़ोन नंबर id, WABA id, मीडिया id — किसी भी अन्य चीज़ से पहले आपकी की से जुड़े अकाउंट के साथ जाँचा जाता है। मिसमैच होने पर कोड 100 मिलता है, जिसमें वही शब्द होते हैं जो Meta उस ऑब्जेक्ट के लिए लिखता है जिसे आप नहीं देख सकते:

Unsupported post request. Object with ID '…' does not exist, cannot be loaded due to missing permissions, or does not support this operation.

यह शब्दावली Meta की ओर से जानबूझकर चुनी गई है और यहाँ भी जानबूझकर उसी की नक़ल की गई है: कोई ऐसा id जो मौजूद है लेकिन किसी और का है, और कोई ऐसा id जो मौजूद ही नहीं है, दोनों में कोई अंतर नहीं दिखना चाहिए, वरना यह एरर दूसरों के फ़ोन नंबरों का पता लगाने का एक ज़रिया बन जाएगा।

मीडिया

चार एंडपॉइंट, Meta के अनुरूप।

मेथडपाथयह क्या करता है
POST/{version}/{phone-number-id}/mediaफ़ाइल अपलोड करें। मल्टीपार्ट, {"id": "…"} लौटाता है।
GET/{version}/{media-id}फ़ाइल के लिए Meta का मेटाडेटा ऑब्जेक्ट।
GET/{version}/{media-id}/downloadबाइट्स।
DELETE/{version}/{media-id}इसे डिलीट करें, {"success": true} लौटाता है।
किसी फ़ाइल को एक बार अपलोड करना और उसे बार-बार भेजनाPOST /{v}/{pnid}/mediaस्वयं फ़ाइल{ id }पुनः उपयोग योग्यPOST /{v}/{pnid}/messagesid का रेफ़रंस देंडिलीवर हुआस्टेटस वेबहुक से आते हैं
अपलोड करने पर एक id मिलता है। यही id आप मैसेज में डालते हैं।

एक जानबूझकर रखा गया अंतर

GET /{version}/{media-id} Meta का मेटाडेटा ऑब्जेक्ट लौटाता है — messaging_product, mime_type, sha256, file_size, id — लेकिन url Meta के लुकअसाइड होस्ट की तरफ़ नहीं, हमारी तरफ़ पॉइंट करता है।

ऐसा होना ज़रूरी भी है। Meta का मीडिया URL केवल WhatsApp अकाउंट के बिज़नेस टोकन से ही फ़ेच किया जा सकता है, जो हमारी तरफ़ रहता है और इसे कभी नहीं छोड़ता। इसलिए हम आपको ऐसा URL देते हैं जिसे आप फ़ेच कर सकते हैं: ऊपर दिया गया डाउनलोड एंडपॉइंट, उसी होस्ट और वर्शन सेगमेंट पर जिसे आपने कॉल किया था, और उसी बेयरर टोकन से प्रमाणित जिसे आप पहले ही भेज चुके हैं।

क्लाइंट उस URL को अपारदर्शी (opaque) मानते हैं और बस अपने टोकन के साथ उस पर GET रिक्वेस्ट करते हैं, यही वजह है कि किसी अनमॉडिफ़ाइड SDK को इसका पता नहीं चलता। अगर आपका कोड होस्टनेम के लिए कोई विशेष स्थिति (special-case) तय करता है, तो सिर्फ़ यही वह एक जगह है जहाँ बदलाव की ज़रूरत होगी।

परमिशन

WizMessage API जैसी ही परमिशन चिप्स, उन्हीं की (keys) पर। परमिशन कहाँ से पढ़ी जाती है यह कॉल पर निर्भर करता है: सेंड एंडपॉइंट इसे रिक्वेस्ट बॉडी से लेता है, क्योंकि Meta हर मैसेज प्रकार को एक ही पाथ पर रखता है; बाक़ी हर जगह यह पाथ और मेथड से आती है।

भेजना और मीडिया:

कॉलपरमिशन
POST /{v}/{pnid}/messages "type": "template" के साथsend_template
वही, image, video, audio, document या sticker का typesend_media
वही, कुछ भी अन्य — text, interactive, reaction, location, contacts, और mark-as-readsend_text
POST /{v}/{pnid}/media — अपलोडsend_media
DELETE /{v}/{media-id}send_media
GET /{v}/{media-id} और /downloadview_messages

अकाउंट प्रबंधन — अकाउंट प्रबंधित करना देखें:

कॉलपरमिशन
GET /{v}/{waba-id}/message_templatesview_templates
POST और DELETE /{v}/{waba-id}/message_templatesmanage_templates
GET /{v}/{waba-id}/template_analyticsview_analytics
बिज़नेस प्रोफ़ाइल, QR कोड, कॉमर्स सेटिंग्स, ब्लॉक लिस्ट, फ़ोन सेटिंग्स और फ़्लो पर GETview_templates
उन्हीं छह पर POSTmanage_profile
DELETE /{v}/{pnid}/message_qrdls/{code} और DELETE /{v}/{pnid}/block_usersmanage_profile

प्रबंधन पक्ष में केवल यही दो DELETE हैं। बिज़नेस प्रोफ़ाइल, कॉमर्स सेटिंग्स, फ़ोन सेटिंग्स या फ़्लो पर कोई डिलीट नहीं होता — इनमें से किसी पर भी भेजा गया DELETE, code 100 के रूप में अस्वीकार कर दिया जाता है, ठीक वैसे ही जैसे किसी ऐसे एंडपॉइंट के लिए होता है जो मौजूद ही नहीं है।

नोट: यहाँ मीडिया अपलोड के लिए send_media की ज़रूरत होती है। WizMessage API पर इसके लिए किसी परमिशन की ज़रूरत नहीं होती, इस तर्क के आधार पर कि send_media ग्राहक को फ़ाइल भेजने को नियंत्रित करता है, न कि Meta के सर्वर पर फ़ाइल रखने को। यह सरफ़ेस अधिक सख्त रुख अपनाता है। अगर आप किसी की (key) को यहाँ पोर्ट कर रहे हैं और अपलोड्स 403 लौटाने लगे हैं, तो इसकी वजह यही है।

नोट: view_templates सिर्फ़ टेम्पलेट्स ही नहीं, उससे कहीं ज़्यादा को नियंत्रित करता है। बिज़नेस प्रोफ़ाइल, QR कोड, कॉमर्स सेटिंग्स, ब्लॉक लिस्ट, फ़ोन सेटिंग्स और फ़्लो को पढ़ना — ये सभी इसके पीछे आते हैं। यह नाम ऐतिहासिक है — यह दूसरी तालिका की हर चीज़ से पहले का है। किसी की (key) का दायरा सीमित करते समय इसे अनटिक कर दें, तो छह असंबद्ध रीड कॉल्स टेम्पलेट्स के बारे में मैसेज के साथ 403 लौटाना शुरू कर देंगे, जो कि कोई मददगार सुराग नहीं है।

नोट: तीन चिप्स केवल Meta Graph के लिए हैं। manage_templates, manage_profile और view_analytics WizMessage API पर किसी चीज़ को नियंत्रित नहीं करते — वे इस पेज पर दिए गए एंडपॉइंट्स के लिए हैं। पहले से मौजूद हर की (key) को ये तीनों दिए गए थे, इसलिए जो काम कर रहा था उसमें से कुछ भी रुका नहीं; दायरा सीमित करना (narrowing) की के एडिट फ़ॉर्म पर जानबूझकर अनटिक करना है।

अस्वीकृति 403 पर Graph code 10 होती है — हमारा PERMISSION_DENIED कभी नहीं। एक ही एरर हैंडलर इस पूरे सरफ़ेस को संभाल लेता है।

परमिशन से पहले ओनरशिप जाँची जाती है। अगर पाथ में मौजूद id वह नहीं है जो आपकी की (key) से जुड़ा है, तो उत्तर code 100 होता है और यह कभी यह नहीं बताता कि आपके पास किस परमिशन की कमी थी — वरना यह एरर अपने आप में दूसरे लोगों के अकाउंट्स को टटोलने का एक तरीक़ा बन जाएगा।

अकाउंट प्रबंधित करना

मैसेज भेजने के अलावा, यह सरफ़ेस Meta के अपने पाथ्स पर Meta के अकाउंट-मैनेजमेंट एंडपॉइंट्स भी उपलब्ध कराता है। आठ रिसोर्स हैं, और आपको किस परमिशन की ज़रूरत है यह इस बात पर निर्भर करता है कि आप पढ़ रहे हैं या लिख रहे हैं।

अकाउंट मैनेजमेंट एंडपॉइंट्स, जिन्हें प्रत्येक के लिए आवश्यक परमिशन के आधार पर समूहीकृत किया गया हैकुछ भी पढ़नासभी आठ रिसोर्सप्रोफ़ाइल, QR कोड, कॉमर्सब्लॉक लिस्ट, सेटिंग्स, फ़्लोटेम्पलेट्सview_templatesअकाउंट में लिखनाप्रोफ़ाइल और उपस्थितिबिज़नेस प्रोफ़ाइल, QR कोडकॉमर्स, ब्लॉक लिस्टसेटिंग्स, फ़्लोmanage_profileटेम्पलेट्स लिखनाबनाना और हटानाmessage_templatesएनालिटिक्स अलग हैmanage_templatesटेम्पलेट एनालिटिक्स की अपनी चिप है: view_analytics.
पढ़ने के लिए एक चिप है। लिखने के लिए यह इस बात पर बँटती है कि आप क्या लिख रहे हैं।

इस सेक्शन के हर एंडपॉइंट के बारे में तीन बातें सच हैं, और यही पूरा कारण हैं कि यह अस्तित्व में आ सका है:

  • रिक्वेस्ट बॉडी Meta की अपनी होती है, जिसे बिना बदले और बिना वैलिडेट किए आगे फ़ॉरवर्ड किया जाता है। हम यहाँ Meta की बॉडीज़ का दोबारा दस्तावेज़ीकरण नहीं करते हैं और न ही हम उन्हें जाँचते हैं। Meta का रेफरेंस ही आधिकारिक स्पेक है, और यदि आप कोई ग़लती करते हैं तो वापसी में Meta का ही एरर मिलता है — जो कि हमारे द्वारा बनाए गए किसी भी एरर से कहीं बेहतर एरर है।
  • बॉडी केवल POST पर भेजी जाती है। रिक्वेस्ट के हमारे सिस्टम से निकलने से पहले ही DELETE से जुड़ी किसी भी बॉडी को ड्रॉप कर दिया जाता है। Meta का टेम्पलेट डिलीट ?name= या ?hsm_id= को क्वेरी पैरामीटर के रूप में लेता है, बॉडी के रूप में नहीं, इसलिए यह दस्तावेज़ के अनुसार ही काम करता है; इसके अलावा कुछ भी जो डिलीट बॉडी की उम्मीद करता है, वह काम नहीं करेगा।
  • आपकी क्वेरी स्ट्रिंग फ़ॉरवर्ड की जाती है, सिवाय access_token और appsecret_proof के। इन दोनों को हटा दिया जाता है, क्योंकि Meta Authorization हेडर के मुक़ाबले क्वेरी-स्ट्रिंग टोकन को प्राथमिकता देता है और उन्हें जाने देने से आपका बेयरर वैकल्पिक हो जाएगा। क्वेरी स्ट्रिंग से ऑथेंटिकेट करने वाला क्लाइंट पाएगा कि इसे चुपचाप अनदेखा कर दिया गया है — हेडर का उपयोग करें।

नोट: इन पाथ्स में WABA id और फ़ोन नंबर id वही होने चाहिए जो आपकी की (key) से जुड़े हैं। हमारे नेटवर्क से कुछ भी बाहर जाने से पहले इसकी जाँच की जाती है, और मेल न खाने पर वही code 100 मिलता है जिसका विवरण जब कोई id आपकी न हो में दिया गया है।

नोट: paging.next Meta की ओर इशारा करता है, हमारी ओर नहीं। रिस्पॉन्स ठीक वैसे ही लौटाए जाते हैं जैसे Meta ने उन्हें भेजा था, इसलिए पेजिनेटेड रिस्पॉन्स में next लिंक एक graph.facebook.com URL होता है — और आपकी API key वहाँ ऑथेंटिकेट नहीं करती। अगले पेज पर जाने के लिए paging.cursors.after लें और इस होस्ट पर ?after= के साथ दोबारा रिक्वेस्ट भेजें।

टेम्पलेट्स

GET    https://wizmessage.com/v26.0/{waba-id}/message_templates?limit=25
POST   https://wizmessage.com/v26.0/{waba-id}/message_templates
DELETE https://wizmessage.com/v26.0/{waba-id}/message_templates?name=order_shipped
मेथडपरमिशनरिटर्न
GETview_templatesMeta का { data, paging }
POSTmanage_templatesMeta का क्रिएट रिस्पॉन्स
DELETEmanage_templatesMeta का डिलीट रिस्पॉन्स

GET, कर्सर पेजिनेशन के लिए limit (1–100, डिफ़ॉल्ट 25) और after स्वीकार करता है।

नोट: GET केवल limit और after स्वीकार करता है। इस एज पर Meta के अन्य फ़िल्टर — name, status, fields, language, category, name_or_content — चुपचाप ड्रॉप कर दिए जाते हैं, रिजेक्ट नहीं किए जाते। ?status=APPROVED के लिए की गई रिक्वेस्ट 200 लौटाती है जिसमें हर टेम्पलेट शामिल होता है, चाहे वह अप्रूव्ड हो या नहीं। अपनी तरफ़ से फ़िल्टर करें, या पूरी सूची को पेजिनेट करने के लिए after का उपयोग करें। इस पूरे पेज पर यही एक ऐसी जगह है जहाँ पोर्ट किए गए क्लाइंट को एरर के बजाय ग़लत जवाब मिलता है, इसलिए इसके लिए अपने कोड की जाँच करना उचित रहेगा।

टेम्पलेट एनालिटिक्स

GET https://wizmessage.com/v26.0/{waba-id}/template_analytics

इसके लिए view_analytics चाहिए। Meta को start की आवश्यकता होती है, और इसके बिना वह code 100 — "(#100) The parameter start is required" — का जवाब देता है। granularity और बाकी पैरामीटर Meta के हैं; उन्हें आगे पास करें और वे बिना किसी बदलाव के पहुँचते हैं।

बिज़नेस प्रोफ़ाइल

GET  https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_business_profile?fields=about,address,description,email,profile_picture_url,websites,vertical
POST https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_business_profile

GET के लिए view_templates चाहिए और यह Meta का { data } लौटाता है। POST के लिए manage_profile चाहिए।

QR कोड

GET    https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls
POST   https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls
DELETE https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls/{code}

GET के लिए view_templates चाहिए और यह Meta का { data } लौटाता है। POST और DELETE के लिए manage_profile चाहिए।

/{code} पाथ केवल DELETE के लिए है। किसी सिंगल कोड पर कोई GET या POST नहीं होता — कलेक्शन को पढ़ें और उसमें से चुनें।

कॉमर्स सेटिंग्स

GET  https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_commerce_settings
POST https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_commerce_settings

GET के लिए view_templates चाहिए और यह Meta का { data } लौटाता है। POST के लिए manage_profile चाहिए।

ब्लॉक किए गए ग्राहक

GET    https://wizmessage.com/v26.0/{phone-number-id}/block_users
POST   https://wizmessage.com/v26.0/{phone-number-id}/block_users
DELETE https://wizmessage.com/v26.0/{phone-number-id}/block_users

GET के लिए view_templates चाहिए और यह Meta का { data } लौटाता है। POST और DELETE के लिए manage_profile चाहिए। ध्यान दें कि अनब्लॉक करना खुद कलेक्शन पर ही DELETE करना है, न कि प्रति-ग्राहक किसी अलग पाथ पर।

फ़ोन नंबर सेटिंग्स

GET  https://wizmessage.com/v26.0/{phone-number-id}/settings
POST https://wizmessage.com/v26.0/{phone-number-id}/settings

GET के लिए view_templates चाहिए और यह { calling, storage_configuration } लौटाता है। POST के लिए manage_profile चाहिए।

नोट: यह पाथ /settings है। कुछ थर्ड-पार्टी API संदर्भ इसे whatsapp_calling_settings कहते हैं — यह पाथ Meta पर मौजूद नहीं है और यहाँ code 2500 लौटाता है, क्योंकि हम इसे आगे फ़ॉरवर्ड करते हैं और Meta इसे रिजेक्ट कर देता है। देखें यहाँ क्या उपलब्ध नहीं है।

फ़्लो

GET  https://wizmessage.com/v26.0/{waba-id}/flows
POST https://wizmessage.com/v26.0/{waba-id}/flows

GET के लिए view_templates चाहिए और यह Meta का { data, paging } लौटाता है। POST के लिए manage_profile चाहिए।

यहाँ क्या उपलब्ध नहीं है

ऊपर बताई गई हर चीज़ की पुष्टि एक लाइव WhatsApp अकाउंट पर की गई थी। नीचे बताई गई हर चीज़ की भी — यही वजह है कि यह सेक्शन आपको बता सकता है कि कोई एंडपॉइंट अनुपलब्ध क्यों है, और आम तौर पर यही तय करता है कि आपको आगे क्या करना है।

अनुपलब्ध एंडपॉइंट क्या लौटाता है। ऊपर दी गई सूची में न होने वाली कोई भी चीज़ ऐसे पाथ के लिए जिसे वह सर्व नहीं करेगा, Meta के अपने शब्दों में जवाब देती है — 400 पर code 100:

Unsupported get request. Object with ID '…' does not exist, cannot be loaded due to missing permissions, or does not support this operation.

ऐसा पाथ जो समर्थित है लेकिन उसे ऐसे मेथड से कॉल किया गया है जो वह ऑफ़र नहीं करता, वही कोड एक छोटे मैसेज के साथ लौटाता है: "Unsupported delete request." दोनों जानबूझकर ऐसे ऑब्जेक्ट से अलग नहीं पहचाने जा सकते जिसे आप बस देख नहीं सकते — कोई ऐसा एरर जो यह पुष्टि करता हो कि कौन-से एंडपॉइंट मौजूद हैं, वह सरफ़ेस को मैप करने का एक तरीक़ा बन जाएगा।

इस सरफ़ेस पर कोई एंडपॉइंट क्यों उपलब्ध नहीं हो सकता हैऐसा एंडपॉइंट जो यहाँ नहीं हैहम इसे अस्वीकार करते हैंregistration, subscribed_appsइससे आपका अकाउंट ख़राब हो जाएगाकोई समाधान नहींMeta इसे अस्वीकार करता हैकोएग्ज़िस्टेंस नंबर पर नहींconversational_automation, callsMeta का अपना जवाबयह मौजूद नहीं हैAPI मिरर से चार पाथMeta code 2500 से जवाब देता हैअसली पाथ का उपयोग करेंचौथा समूह अभी बस हमारी सूची में नहीं है — नीचे देखें।
चार कारण, और उनमें से सिर्फ़ एक हमारा है।

जानबूझकर अस्वीकार किए गए

कुछ भी फ़ॉरवर्ड करने से पहले, इन्हें हर मेथड पर ब्लॉक कर दिया जाता है:

पाथकारण
register, deregister, request_code, verify_codeकोएग्ज़िस्टेंस नंबर को Cloud API पर कभी भी रजिस्टर नहीं किया जाना चाहिए। ऐसा करने से ही अकाउंट के हर सेंड में एरर 133010 आने लगता है, और इसे आपकी तरफ़ से वापस ठीक नहीं किया जा सकता।
subscribed_appsGET सहित सभी मेथड। यहाँ DELETE करने से आपके अपने WhatsApp अकाउंट से हमारे वेबहुक अनसब्सक्राइब हो जाएँगे और बिना किसी चेतावनी के आपका अपना इंटीग्रेशन टूट जाएगा; ऐसा पाथ खुला छोड़ने के बजाय जहाँ एक चूक से ऐसा हो जाए, हम इसे रीड करने की सुविधा भी नहीं देते।
marketing_messagesमार्केटिंग सेंड डैशबोर्ड के कैंपेन टूल्स से होकर जाते हैं, जो प्रति-अकाउंट सेंड रेट लागू करते हैं।
/{template-id}/unpauseMeta पाथ में बिना किसी अकाउंट के सिर्फ़ एक आईडी से टेम्पलेट की पहचान करता है, इसलिए उस पर कोई कार्रवाई करने से पहले हम यह साबित नहीं कर सकते कि टेम्पलेट आपका है। इसे डैशबोर्ड से अनपॉज़ करें।
POST के अलावा किसी भी अन्य मेथड पर messagesसेंड पाथ में रेट लिमिटर और अकाउंट-सस्पेंशन हैंडलिंग शामिल होती है। सिर्फ़ POST को रूट किया जाता है।

कोएग्ज़िस्टेंस नंबर पर उपलब्ध नहीं

Meta के अपने जवाब, 10 अगस्त 2026 को एक लाइव अकाउंट पर जाँचे गए:

पाथMeta का जवाब
/{phone-number-id}/conversational_automationcode 100 — "Tried accessing nonexisting field"
/{phone-number-id}/callscode 100 — "Tried accessing nonexisting field"
/{phone-number-id}/groups500 पर code 131000

ये WhatsApp Business ऐप के साथ कोएग्ज़िस्टेंस में चलने वाले नंबरों पर Meta की पाबंदियाँ हैं, हमारी नहीं — हम रिक्वेस्ट फ़ॉरवर्ड करते हैं और यही वापस मिलता है। Meta समय-समय पर उपलब्धता बढ़ाता रहता है, इसलिए यदि इनमें से कोई आपके काम का है, तो इस टेबल पर हमेशा के लिए निर्भर रहने के बजाय दोबारा टेस्ट करना बेहतर है।

ऐसे पाथ जो कहीं भी मौजूद नहीं हैं

इनमें से हर एक थर्ड-पार्टी API संदर्भों में दिखाई देता है और यह कोई Meta एंडपॉइंट नहीं है। चारों code 2500 लौटाते हैं, "Unknown path components":

आपने शायद क्या पढ़ा होगाइसके बजाय क्या इस्तेमाल करें
POST /{phone-number-id}/mark_message_as_readstatus: "read" बॉडी के साथ POST /{phone-number-id}/messages — देखें मैसेज को पढ़ा हुआ मार्क करना
GET /{phone-number-id}/message_statusडिलीवरी स्टेटस आपके वेबहुक पर आते हैं; देखें आप क्या प्राप्त करते हैं यह चुनना
/{phone-number-id}/whatsapp_calling_settings/{phone-number-id}/settings
/{phone-number-id}/conversational_componentsकुछ नहीं — सबसे क़रीबी असली पाथ conversational_automation है, जो किसी कोएग्ज़िस्टेंस नंबर पर उपलब्ध नहीं है

Meta पर मौजूद हैं, हमारी सूची में नहीं

GET /{waba-id}/phone_numbers Meta पर काम करता है और यहाँ न तो ब्लॉक है और न ही फ़ॉरवर्ड किया जाता है, इसलिए यह code 100 जवाब देता है। यह उन पहले एंडपॉइंट्स में से एक है जिसे Cloud API क्लाइंट कॉल करता है, इसलिए इसका ज़िक्र करना ज़रूरी है: आपकी key पहले से ही ठीक एक फ़ोन नंबर को पिन करती है, और उसकी id वही है जिसे आप इस पेज के हर पाथ में डालते हैं। आप इसे डैशबोर्ड में key के Overview टैब से देख सकते हैं।

बेयर नोड रीड्स

GET /{v}/{waba-id}?fields=… और GET /{v}/{phone-number-id}?fields=… Meta पर काम करते हैं लेकिन यहाँ नहीं। इस सरफ़ेस पर सिंगल-सेगमेंट पाथ एक media id होता है — GET /{v}/{media-id} का यही मतलब है — इसलिए उस जगह पर WABA id को मीडिया के रूप में खोजा जाता है और वह फ़ेल हो जाता है।

यदि आपको इसकी उम्मीद न हो तो यह फ़ेल होना उलझन में डाल सकता है: यह सबसे पहले view_messages की जाँच करता है, इसलिए उस अनुमति के बिना वाली key को 403 मिलता है जिसमें ऐसी अनुमति का नाम दिया होता है जिसका पूछे गए अनुरोध से कोई लेना-देना नहीं होता। इसके बजाय एज फ़ॉर्म्स का उपयोग करें — /{waba-id}/message_templates, /{phone-number-id}/settings, और अकाउंट प्रबंधित करना का बाक़ी हिस्सा।

Meta के फ़ॉर्मेट में वेबहुक

डैशबोर्ड का वेबहुक टैब एक पेलोड फ़ॉर्मेट पर खुलता है। WizMessage (v1) वह पेलोड है जिसका दस्तावेज़ीकरण दूसरा पेज करता है; जब तक आप इसे बदलते नहीं हैं, एक key इसी का उपयोग करती है।

WizMessage पर सेट पेलोड फ़ॉर्मेट के साथ Webhooks टैब, जिसमें v1 इवेंट के चेकबॉक्स दिख रहे हैं

Meta Graph चुनें और आपका एंडपॉइंट हमारे {version, event, timestamp, data} पेलोड को प्राप्त करना बंद कर देता है और Meta द्वारा हमें भेजा गया एनवेलप, ज्यों का त्यों फ़ॉरवर्ड किया हुआ प्राप्त करना शुरू कर देता है — प्रति बदलाव एक डिलीवरी।

{
	"object": "whatsapp_business_account",
	"entry": [
		{
			"id": "102290129340398",
			"time": 1770000123,
			"changes": [
				{
					"value": {
						"messaging_product": "whatsapp",
						"metadata": {
							"display_phone_number": "15550783881",
							"phone_number_id": "106540352242922"
						},
						"contacts": [{ "profile": { "name": "Priya Sharma" }, "wa_id": "919876543210" }],
						"messages": [
							{
								"from": "919876543210",
								"id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAEhgg…",
								"timestamp": "1770000123",
								"type": "text",
								"text": { "body": "Has it shipped yet?" }
							}
						]
					},
					"field": "messages"
				}
			]
		}
	]
}

यदि आपके पास पहले से ही कोई Cloud API वेबहुक हैंडलर है, तो वह इसी आकार के लिए लिखा गया होता है।

फ़ॉर्मेट बदलने से यह भी बदल जाता है कि टैब आपसे क्या मांगता है: इवेंट चेकबॉक्स की जगह Meta के अपने फ़ील्ड नाम आ जाते हैं, और एक वेरीफ़ाई टोकन दिखाई देने लगता है।

Meta Graph फ़ॉर्मेट में Webhooks टैब, जिसमें वेरीफ़ाई टोकन और सब्सक्राइब करने योग्य 9 Meta फ़ील्ड नाम दिख रहे हैं

इसे सेव करने से पहले

तीन चीज़ों की आवश्यकता होती है, और डैशबोर्ड आपको बताएगा कि इनमें से क्या छूटा हुआ है:

Meta Graph वेबहुक को सेव करने से पहले किन चीज़ों का होना ज़रूरी हैWebhook सीक्रेटसिग्नेचर की कुंजी बनता हैवेरीफ़ाई टोकनसाबित करता है कि URL आपका हैएक लाइव URLसेव करने से पहले हम इसे कॉल करते हैंसेव हो गयाडिलीवरी शुरू होती हैकोई ऐसा URL जो अभी जवाब नहीं दे रहा है, उसे सेव नहीं किया जा सकता। पहले डिप्लॉय करें, फिर कॉन्फ़िगर करें।
जब आप सेव दबाते हैं, तो इसी क्रम में तीनों की जाँच की जाती है।
  • एक वेबहुक सीक्रेट। यही एकमात्र चीज़ है जो X-Hub-Signature-256 को की (key) करती है, इसलिए इसके बिना कोई डिलीवरी अनसाइंड और असत्यापनीय होगी। key के Webhooks टैब पर इसे जनरेट करें।
  • एक वेरीफ़ाई टोकन। अपनी पसंद की कोई भी स्ट्रिंग; आपके एंडपॉइंट को भी यह पता होनी चाहिए।
  • एक URL जो पहले से जवाब दे रहा हो। नीचे देखें।

वेरीफ़िकेशन हैंडशेक

जब आप सेव करते हैं, तो हम आपके URL को ठीक वैसे ही कॉल करते हैं जैसे Meta करता:

GET https://your-server.example/webhooks
	?hub.mode=subscribe
	&hub.verify_token=<the token you set>
	&hub.challenge=482910337

आपके एंडपॉइंट को यह जाँचना होगा कि hub.verify_token आपके द्वारा कॉन्फ़िगर किए गए मान से मेल खाता है, फिर पूरी रिस्पॉन्स बॉडी के रूप में hub.challenge के साथ 200 का जवाब देना होगा — कोई JSON रैपर नहीं, कोई कोट्स नहीं, कुछ और नहीं। यह चैलेंज एक 9-अंकों की संख्या है, इसलिए इको करने से पहले parseInt करने वाला हैंडलर इसे बिना किसी बदलाव के वापस भेज देता है।

यदि चैलेंज हूबहू वापस नहीं आता है, तो सेव करने से मना कर दिया जाता है और कुछ भी स्टोर नहीं किया जाता। यही बात किसी को हमारी डिलीवरी कतार को किसी ऐसे URL की ओर निर्देशित करने से रोकती है जिस पर उसका नियंत्रण नहीं है।

// express
app.get('/webhooks', (req, res) => {
	if (req.query['hub.mode'] === 'subscribe' && req.query['hub.verify_token'] === VERIFY_TOKEN) {
		return res.status(200).send(req.query['hub.challenge'])
	}
	res.sendStatus(403)
})

सिग्नेचर को वेरीफ़ाई करना

हर डिलीवरी में X-Hub-Signature-256 होता है, जिसकी गणना Meta के तरीके से ही की जाती है: रॉ रिक्वेस्ट बॉडी का HMAC-SHA256, जो आपके वेबहुक सीक्रेट पर की (keyed) होता है, हेक्स में, और जिसके आगे sha256= लगा होता है।

हेडरमान
X-Hub-Signature-256sha256= + रॉ बॉडी का HMAC-SHA256, आपके वेबहुक सीक्रेट पर की (keyed), लोअरकेस हेक्स।
X-Webhook-Eventmeta.<field> — यह डिलीवरी किस फ़ील्ड को लाती है।
X-Webhook-Idइस डिलीवरी प्रयास के लिए यूनीक आईडी। इसके आधार पर डिडुप करें।
User-Agentfacebookplatform/1.0 (+http://developers.facebook.com)

ध्यान दें: यह WizMessage फ़ॉर्मेट जैसा डेरिवेशन नहीं है। वह timestamp + "." + rawBody को साइन करता है और टाइमस्टैम्प को उसके अपने हेडर में भेजता है; यह सिर्फ़ बॉडी को साइन करता है, जिसमें कहीं भी कोई टाइमस्टैम्प नहीं होता। यदि आप एक ही सर्वर पर दोनों फ़ॉर्मेट चला रहे हैं, तो दोनों वेरीफ़ायर अलग-अलग रखें — एक साझा वेरीफ़ायर उस फ़ॉर्मेट पर विफल हो जाएगा जिसके लिए उसे नहीं लिखा गया था।

प्राप्त हुए रॉ बाइट्स को वैसे ही साइन करें। JSON को पार्स करने और दोबारा सीरियलाइज़ करने से की (key) का क्रम और स्पेसिंग बदल जाती है, और सिग्नेचर कभी मेल नहीं खाएगा।

const crypto = require('node:crypto')

// express: app.post('/webhooks', express.raw({ type: 'application/json' }), ...)
function verify(req) {
	const provided = req.get('X-Hub-Signature-256') || ''
	if (!provided.startsWith('sha256=')) return false

	const expected = crypto
		.createHmac('sha256', WEBHOOK_SECRET)
		.update(req.body) // the raw Buffer, not a parsed object
		.digest('hex')

	// Constant-time compare — a plain === leaks timing information.
	const a = Buffer.from(expected, 'hex')
	const b = Buffer.from(provided.slice('sha256='.length), 'hex')
	return a.length === b.length && crypto.timingSafeEqual(a, b)
}

चुनना कि आप क्या प्राप्त करते हैं

WizMessage फ़ॉर्मेट में आप इवेंट्स पर टिक करते हैं। इसमें आप Meta के फ़ील्ड नामों पर टिक करते हैं, जो उस चीज़ से मेल खाते हैं जिसे आप Meta के अपने App Dashboard में सब्सक्राइब करते हैं।

फ़ील्डक्या प्राप्त होता है
messagesइनबाउंड मैसेज और डिलीवरी स्टेटस। नीचे दिया गया नोट पढ़ें।
message_statusडिलीवरी स्टेटस, उनके अपने फ़ील्ड के रूप में।
smb_message_echoesवे मैसेज जो बिज़नेस ने अपने फ़ोन पर WhatsApp Business ऐप से भेजे।
smb_app_state_syncउस फ़ोन पर एड्रेस-बुक में किए गए बदलाव।
user_id_updateकिसी संपर्क की WhatsApp पहचान बदल गई।
message_template_status_updateकोई टेम्पलेट स्वीकृत, अस्वीकृत या रोक दिया गया।
message_template_quality_updateकिसी टेम्पलेट का क्वालिटी स्कोर बदल गया।
account_updateWhatsApp अकाउंट कनेक्ट, डिस्कनेक्ट, प्रतिबंधित या ऑफ़बोर्ड हुआ।
historyशुरुआती सिंक के दौरान पिछली बातचीत। बड़े पेलोड — केवल तभी ऑप्ट-इन करें यदि आप उन्हें चाहते हैं।

नए graph वेबहुक केवल messages के सब्सक्रिप्शन के साथ शुरू होते हैं। हर फ़ील्ड को साफ़ करने से कॉन्फ़िगरेशन हटाए बिना डिलीवरी बंद हो जाती है।

ध्यान दें: messages में पहले से ही डिलीवरी स्टेटस शामिल होते हैं। Meta दोनों को "field": "messages" के तहत भेजता है — इनबाउंड मैसेज messages ऐरे में, और उसी वैल्यू ऑब्जेक्ट पर statuses ऐरे में डिलीवरी रिपोर्ट। इसलिए किसी भेजे गए मैसेज से आपको वापस मिली wamid को कोरिलेट करने के लिए डिफ़ॉल्ट सब्सक्रिप्शन ही काफ़ी है। message_status एक अतिरिक्त फ़ील्ड है, वह नहीं जिसकी आपको बुनियादी स्टेटस ट्रैकिंग के लिए ज़रूरत होती है। यह मानने से पहले कि आपका कोई सब्सक्रिप्शन छूट गया है, value.statuses को पढ़ें।

तीन बातें जो WizMessage फ़ॉर्मेट से अलग हैं

यदि आप किसी इंटीग्रेशन को इस पर ले जा रहे हैं, तो इसे पढ़ना उपयोगी है, क्योंकि इनमें से हर एक बात चुपचाप यह बदल देती है कि क्या प्राप्त होगा।

दोनों वेबहुक फ़ॉर्मेट के बीच अलग होने वाले तीन व्यवहारकोई चैटबॉट गेट नहींदोनों ही तरह से डिलीवर होता हैv1 के लिए bot mode = Webhook ज़रूरी हैGraph उस सेटिंग को अनदेखा करता हैआपको sent मिलता हैऔर कैंपेन स्टेटस भीv1 दोनों को फ़िल्टर कर देता हैGraph सब कुछ फ़ॉरवर्ड करता हैकोई सिंथेटिक sent नहींबदले में Meta के अपने इवेंटsmb_message_echoesऔर स्टेटसGraph फ़ॉर्मेट पर v1 पर उसी अकाउंट द्वारा जनरेट किए गए ट्रैफ़िक की तुलना में अधिक ट्रैफ़िक की अपेक्षा करें।
ये तीनों Graph फ़ॉर्मेट को कम नहीं, बल्कि ज़्यादा डिलीवर करने वाला बनाते हैं।
  • डिलीवरी चैटबॉट सिस्टम पर निर्भर (gated) नहीं है। WizMessage फ़ॉर्मेट में, इनबाउंड मैसेज आपके एंडपॉइंट तक केवल तभी पहुँचते हैं जब अकाउंट का चैटबॉट सिस्टम Webhook पर सेट हो। Graph फ़ॉर्मेट उस सेटिंग को पूरी तरह से अनदेखा करता है — किसी URL को कॉन्फ़िगर करना और किसी फ़ील्ड को सब्सक्राइब करना ही पूरा ऑप्ट-इन है।
  • आपको status: "sent" और कैंपेन स्टेटस प्राप्त होते हैं। WizMessage फ़ॉर्मेट जानबूझकर दोनों को छोड़ देता है। यहाँ आपको वह सब मिलता है जो Meta ने भेजा है, जिसका अर्थ है कि बल्क कैंपेन चलाने वाले अकाउंट पर काफ़ी अधिक स्टेटस ट्रैफ़िक आएगा।
  • कोई सिंथेटिक message.sent नहीं है। WizMessage फ़ॉर्मेट API, डैशबोर्ड या फ़ोन से भेजे गए मैसेज के लिए एक सिंथेटिक इवेंट तैयार करता है। Meta smb_message_echoes और sent स्टेटस के साथ इसी ज़रूरत को पूरा करता है, इसलिए यहाँ कुछ भी कृत्रिम रूप से नहीं बनाया जाता।

डिलीवरी, दोबारा प्रयास और बंद करना

WizMessage फ़ॉर्मेट के बिल्कुल समान — वही तालिका लागू होती है। संक्षेप में: हम 10 सेकंड प्रतीक्षा करते हैं, कभी भी रीडायरेक्ट का पालन नहीं करते, बैकऑफ़ के साथ 5xx/408/429/टाइमआउट का 5 बार दोबारा प्रयास करते हैं, अन्य 4xx का कभी दोबारा प्रयास नहीं करते, और 410 Gone को "इस वेबहुक को बंद करें" मानते हैं।

डिलीवरी कम-से-कम एक बार (at-least-once) होती है। X-Webhook-Id के आधार पर डिडुप करें, और तुरंत 2xx जवाब दें।

बिना कोड लिखे इसे आज़माना

की के Test API डायलॉग में एक API Format कंट्रोल होता है। इसे Meta Graph पर सेट कीजिए और एंडपॉइंट पिकर आपके अकाउंट के वास्तविक टारगेट — POST /v26.0/{your phone number id}/messages — से बदल जाता है, जिसमें Meta के प्रारूप वाली बॉडी पहले से भरी होती है।

Meta Graph मोड में Test API डायलॉग, जिसमें रीड-ओनली मैसेज एंडपॉइंट और Meta के प्रारूप वाली रिक्वेस्ट बॉडी दिखाई गई है

"Simulate Only" Meta से संपर्क किए बिना रिक्वेस्ट को वापस लौटाता है; Send Real Message पर स्विच करने से यह इसे भेज देता है और आपको Meta का वास्तविक रिस्पॉन्स दिखाता है, एरर एनवेलप समेत सब कुछ।

यह डायलॉग सिर्फ़ POST /{phone-number-id}/messages को टारगेट करता है और किसी अन्य चीज़ को नहीं, इसलिए अकाउंट-प्रबंधन एंडपॉइंट्स तक यहाँ से नहीं पहुँचा जा सकता — उन्हें curl या अपने क्लाइंट के साथ आज़माकर देखें।

Get code में भी यही कंट्रोल होता है, इसलिए जनरेट हुआ स्निपेट आपके द्वारा चुने गए सरफ़ेस को टारगेट करता है, सभी आठ भाषाओं में से किसी में भी। जिस की का इस्तेमाल आप यहाँ करना चाहते हैं, उस पर "Require signature" बंद रखें — इसके चालू होने पर, जनरेट हुआ Graph स्निपेट रिक्वेस्ट को साइन भी करता है, जो एकमात्र ऐसी चीज़ है जो एक अनमॉडिफ़ाइड Cloud API क्लाइंट नहीं कर सकता।