अपने सॉफ़्टवेयर को WhatsApp से जोड़ना

API Management वह ज़रिया है जिससे कोई दूसरा सिस्टम — आपका बिलिंग सॉफ़्टवेयर, आपका ऑनलाइन स्टोर, आपका अपना बैकएंड — WizMessage के ज़रिये WhatsApp मैसेज भेजता है। यहाँ आप उसे एक API key जारी करते हैं, बताते हैं कि वह कौन-सा अप्रूव्ड WhatsApp टेम्पलेट भेज सकता है, और उसे एक वेबहुक से जोड़ देते हैं ताकि जवाब वापस आ सकें। यह गाइड पूरा रास्ता दिखाती है, और फिर उस REST API का ब्यौरा देती है जिसे आपके डेवलपर कॉल करेंगे।

डैशबोर्ड

आपकी API keys कहाँ रहती हैं

आपकी जारी की हुई हर key यहाँ API Keys के नीचे दिखती है। हर पंक्ति में key का स्टेटस, उसका पब्लिक प्रीफ़िक्स (key बनाने के बाद उसका बस यही हिस्सा दोबारा दिखाया जाता है), और आज उसने कितनी कॉल की हैं, यह दिखता है। "Manage" उस key को खोलता है; टॉगल उसे डिलीट किए बिना रोक देता है।

1. ▶ आपकी API keys कहाँ रहती हैं
2. ▶ ऐसी key जो अभी पूरी नहीं हुई है

ऐसी key जो अभी पूरी नहीं हुई है

जिस key से कोई टेम्पलेट मैप नहीं है, उस पर "Needs setup" बैज लगा रहता है। वह ऑथेंटिकेट तो कर सकती है, लेकिन जब तक आप कोई टेम्पलेट मैप नहीं करते तब तक टेम्पलेट मैसेज नहीं भेज सकती — यानी अधूरा कॉन्फ़िगर किया गया इंटीग्रेशन बाद में भेजते समय फ़ेल होने के बजाय एक नज़र में ही दिख जाता है।

निर्देशित सेटअप

चरण 1 — आप क्या जोड़ रहे हैं?

"Connect your software" एक चार-चरणों वाला विज़ार्ड खोलता है। शुरुआत key को उस सिस्टम का नाम देकर करें जो उसे इस्तेमाल करेगा, और उससे मेल खाता प्रीसेट चुनें। प्रीसेट सिर्फ़ काम के फ़ील्ड नाम सुझाते हैं — बिलिंग प्रीसेट invoice_number, amount, due_date, customer_name सुझाता है — वे यह सीमित नहीं करते कि आप क्या मैप कर सकते हैं।

1. ▶ चरण 1 — आप क्या जोड़ रहे हैं?
2. ▶ चरण 2 — मैसेज चुनें
3. ▶ चरण 3 — जवाब कहाँ जाने चाहिए?
4. ▶ चरण 4 — लाइव करें

चरण 2 — मैसेज चुनें

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

चरण 3 — जवाब कहाँ जाने चाहिए?

जब कोई आपके मैसेज का जवाब देता है, या कोई डिलीवरी रिपोर्ट वापस आती है, तो हम उसे आपके नियंत्रण वाले URL पर POST कर देते हैं। अगर आपका सिस्टम सिर्फ़ भेजता ही है तो इसे बंद रहने दें। आप इसे बाद में key के Webhooks टैब से जोड़ सकते हैं — यहाँ कुछ भी स्थायी नहीं है।

चरण 4 — लाइव करें

पिछले चरण पर Next दबाना ही असल में key बनाता है — यह स्क्रीन उसकी पुष्टि है। तीनों मान अभी कॉपी कर लें: API key, API secret और वेबहुक साइनिंग सीक्रेट ठीक एक ही बार दिखाए जाते हैं और बाद में इन्हें वापस नहीं पाया जा सकता। अगर सीक्रेट खो गया तो आपको उसे रोटेट करना पड़ेगा, यानी जो भी सिस्टम उसे इस्तेमाल कर रहा था उसे अपडेट करना होगा।

key को मैनेज करना

Overview

key खोलते ही आप Overview पर पहुँचते हैं: वह क्या कर सकती है, कितनी इस्तेमाल हो रही है, और किन एंडपॉइंट को कॉल कर सकती है। उपयोग की गिनती रिक्वेस्ट लॉग से पढ़ी जाती है, इसलिए वह असली ट्रैफ़िक दिखाती है।

1. ▶ Overview

ऐसी key जिसे अब भी सेट अप करना बाकी है

जिस key से कोई टेम्पलेट मैप नहीं है, वह इसके बजाय Setup टैब पर खुलती है — वही विज़ार्ड, इनलाइन। ध्यान दें कि टैब पिछले स्क्रीनशॉट से अलग हैं: जब तक किसी key के पास कम से कम एक टेम्पलेट न हो, Templates और Webhooks दिखाए ही नहीं जाते, क्योंकि उनके काम करने के लिए अभी कुछ है ही नहीं।

1. ▶ ऐसी key जिसे अब भी सेट अप करना बाकी है

Templates

हर कार्ड एक ऐसा टेम्पलेट है जिसे यह key भेज सकती है। बॉडी टेक्स्ट वही मैसेज है जो Meta पर अप्रूव हुआ है, और उसके नीचे की चिप्स वे वेरिएबल नाम हैं जो आपका सिस्टम भरकर देगा। "Try it" एक टेस्ट भेजता है, "Get code" आठ भाषाओं में तैयार रिक्वेस्ट बना देता है।

1. ▶ Templates
2. ▶ वेरिएबल पढ़ना — यही एक चीज़ है जिस पर ठहरकर ध्यान देना चाहिए

वेरिएबल पढ़ना — यही एक चीज़ है जिस पर ठहरकर ध्यान देना चाहिए

payment_failed_alert कार्ड को देखिए। उसका मैसेज पहले {{1}}, फिर {{3}}, फिर {{2}} के क्रम में चलता है — टेक्स्ट में प्लेसहोल्डर संख्या-क्रम में नहीं हैं। नीचे दी गई चिप्स संख्या-क्रम में सूचीबद्ध हैं: customer_name {{1}} में भरता है, renewal_date {{2}} में, और plan_name {{3}} में। अपने मानों को हमेशा संख्या से मिलाइए, कभी उस क्रम से नहीं जिसमें प्लेसहोल्डर वाक्य में दिख जाते हैं। यह चूक सबसे ज़्यादा अनूदित टेम्पलेट में होती है, जहाँ शब्द-क्रम बदलने से प्लेसहोल्डर इधर-उधर खिसक जाते हैं।

हर टेम्पलेट पर मौजूद तीन बटन

"Try it" — बिना कोई कोड लिखे टेस्ट भेजें

पेपर-प्लेन बटन इस टेम्पलेट को हर वेरिएबल नाम के लिए एक-एक नमूना मान के साथ पहले से भरा हुआ खोलता है। आपके डेवलपर इसे छुएँ, उससे पहले मैपिंग सही है या नहीं यह जाँचने का यही सबसे तेज़ तरीका है। टॉगल पर ध्यान दें: "Simulate Only" डिफ़ॉल्ट है और कुछ भी बाहर नहीं जाता — सर्वर आपका पेलोड जस का तस लौटा देता है। इसे "Send Real Message" पर करते ही बॉक्स में लिखे नंबर पर असली WhatsApp मैसेज चला जाता है, और उसका शुल्क भी लगता है।

1. ▶ “Try it” — बिना कोई कोड लिखे टेस्ट भेजें
2. ▶ सिमुलेटेड सेंड आपको क्या लौटाता है
3. ▶ “Get code” — रिक्वेस्ट, आपके लिए लिखी हुई
4. ▶ भाषा बदलना
5. ▶ “Edit” — बदलें कि आपका सिस्टम क्या भेजता है
6. ▶ Test API — वही टूल, कोई भी एंडपॉइंट
7. ▶ Webhooks — जवाब वापस पाना

सिमुलेटेड सेंड आपको क्या लौटाता है

Simulate Only मोड में Send Request दबाने पर रिक्वेस्ट वैसी ही लौटती है जैसी प्लेटफ़ॉर्म को मिली थी, साथ में HTTP स्टेटस और राउंड-ट्रिप समय। इसे बनावट की जाँच मानिए, पूर्वाभ्यास नहीं: यह पुष्टि करता है कि आपका JSON पढ़ा गया और key स्वीकार हुई, लेकिन यह आपके वेरिएबल नामों को मैपिंग के विरुद्ध जाँचता नहीं है और Meta से कभी संपर्क नहीं करता। जो पेलोड सिमुलेशन में साफ़ निकलता है, वह असल भेजने पर फिर भी अस्वीकार हो सकता है। मैपिंग को असल में परखने के लिए Send Real Message चालू कीजिए और अपने ही फ़ोन पर भेजिए।

"Get code" — रिक्वेस्ट, आपके लिए लिखी हुई

एंगल-ब्रैकेट वाला बटन ठीक इसी टेम्पलेट के लिए आठ भाषाओं में चलने लायक रिक्वेस्ट बनाता है: cURL, JavaScript, Node.js, Python, PHP, Ruby, Go और C#. जो भी इंटीग्रेशन लिख रहा है, उसे यह सौंप दीजिए। वेरिएबल आपकी मैपिंग के नाम वाले {{placeholders}} के रूप में दिखते हैं, और क्रेडेंशियल YOUR_API_KEY / YOUR_API_SECRET के रूप में छोड़ दिए जाते हैं — यह डायलॉग आपकी असली key कभी नहीं छापता, इसलिए स्निपेट किसी टिकट में चिपकाना सुरक्षित है।

भाषा बदलना

ऊपर दी किसी भी भाषा पर क्लिक कीजिए और स्निपेट उसी के लिए दोबारा लिख दिया जाता है — वही कॉल, वही हेडर, उस भाषा का HTTP क्लाइंट। हर स्निपेट पहली बार क्लिक करने पर ही बनता है, इसलिए पहली बार बदलने पर थोड़ी देर का स्पिनर सामान्य है। Copy स्निपेट को जस का तस उठा लेता है: वह पूरा है, इम्पोर्ट समेत, और अगर इस key के लिए साइनेचर ज़रूरी हैं तो साइनिंग चरण भी उसमें पहले से मौजूद है।

"Edit" — बदलें कि आपका सिस्टम क्या भेजता है

पेंसिल मैपिंग को ही खोलती है। ऊपर दिया फ़ोन मॉक-अप असली मैसेज है जिसमें आपके मौजूदा नाम भर दिए गए हैं, इसलिए आप देख सकते हैं कि ग्राहक क्या पढ़ेगा। उसके नीचे, पहचाने गए हर वेरिएबल का नाम बदला जा सकता है, क्रम बदला जा सकता है, उसे अनिवार्य किया जा सकता है या कोई प्रकार दिया जा सकता है — तारीख़, मुद्रा राशि, इमेज। किसी वेरिएबल का नाम बदलने पर वह आपके API पेलोड में भी बदल जाता है, इसलिए जो सिस्टम अब भी पुराना नाम भेज रहा है वह फ़ेल होने लगेगा: दोनों को साथ-साथ बदलिए।

Test API — वही टूल, कोई भी एंडपॉइंट

टैब के ऊपर मौजूद "Test API" दरअसल टेम्पलेट की बंदिश के बिना "Try it" ही है: तीनों सेंड एंडपॉइंट में से कोई भी चुनिए, दूसरे ड्रॉपडाउन से टेम्पलेट बदलिए, और बॉडी को जैसे चाहें बदलिए। इसका इस्तेमाल कच्ची /messages/text या /messages/template कॉल जाँचने के लिए कीजिए, जिनका अपना कोई कार्ड नहीं है क्योंकि वे किसी मैपिंग से बँधी नहीं हैं। ध्यान दें कि इस टेम्पलेट के वेरिएबल अब भी body_1, body_2, body_3 कहलाते हैं — बिना मैपिंग वाला टेम्पलेट ऐसा ही दिखता है, और इसी को ठीक करने के लिए "Edit" है।

जवाब

Webhooks — जवाब वापस पाना

भेजना तो इंटीग्रेशन का आधा हिस्सा ही है। अपने HTTPS एंडपॉइंट पर एक वेबहुक लगाइए और WizMessage उस पर इनबाउंड मैसेज और डिलीवरी अपडेट POST करेगा। साइनिंग सीक्रेट जनरेट होते समय एक ही बार दिखाया जाता है; हर डिलीवरी पर उसे वेरिफ़ाई कीजिए ताकि आपको पक्का पता रहे कि कॉल वाकई हमारी ओर से आई है।

REST API रेफ़रेंस

ऊपर की हर चीज़ key को कॉन्फ़िगर करती है। असल में आपके डेवलपर यही कॉल करते हैं। बेस URL /api/v1/external है। हर एंडपॉइंट के लिए नीचे दिए ऑथ हेडर ज़रूरी हैं और वह key की रेट लिमिट के दायरे में आता है।

ऑथेंटिकेशन

हर रिक्वेस्ट के साथ अपनी API key भेजें। अगर key पर "Require signature" चालू है, तो आपको रिक्वेस्ट को साइन भी करना होगा — और जिस key पर यह चालू है, वह बिना साइन की गई किसी भी कॉल को सीधे अस्वीकार कर देगी।

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

const crypto = require('node:crypto')

const body = JSON.stringify({ to: '+919876543210', message: 'Hello' })
const timestamp = Math.floor(Date.now() / 1000).toString()

const secretHash = crypto.createHash('sha256').update(API_SECRET).digest('hex')
const signature = crypto.createHmac('sha256', secretHash)
	.update(timestamp + '.' + body)
	.digest('hex')

await fetch('https://your-host/api/v1/external/messages/text', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'X-API-Key': API_KEY,
		'X-Timestamp': timestamp,
		'X-API-Signature': signature,
	},
	body,
})

एंडपॉइंट

मैप किया गया टेम्पलेट भेजना

यह वह पेलोड है जो Templates टैब के साथ जोड़ी बनाता है। आप वेरिएबल नाम से भेजते हैं — वही नाम जो टेम्पलेट कार्ड पर चिप्स के रूप में दिखते हैं — और प्लेटफ़ॉर्म आपके लिए Meta के components तैयार कर देता है। टेम्पलेट मैप करने का पूरा मक़सद यही है: आपके बिलिंग सिस्टम को Meta के component फ़ॉर्मैट के बारे में कुछ भी जानने की ज़रूरत नहीं पड़ती।

POST /api/v1/external/messages/template/send

{
	"to": "+919876543210",
	"template_name": "payment_failed_alert",
	"language": "en",
	"variables": {
		"customer_name": "Priya Sharma",
		"renewal_date": "12 Aug 2026",
		"plan_name": "Wiz Pro"
	},
	"reference": "invoice-2026-0817"
}

नोट: वेरिएबल नाम मैपिंग से बिल्कुल मेल खाने चाहिए — अनजाना नाम नज़रअंदाज़ कर दिया जाता है, और कोई ज़रूरी नाम छूट जाए तो रिक्वेस्ट 400 के साथ अस्वीकार हो जाती है। reference आपका अपना है: यह वेबहुक पर वापस लौटाया जाता है ताकि आप किसी डिलीवरी रिपोर्ट को अपने सिस्टम के किसी रिकॉर्ड से जोड़ सकें।

रेट लिमिट

हर key की अपनी लिमिट होती है, जो Overview टैब पर दिखती है — डिफ़ॉल्ट रूप से 60 रिक्वेस्ट/मिनट और 1,000 मैसेज/दिन। जवाबों में बची हुई सीमा शामिल रहती है, इसलिए सीमा खत्म होने पर दीवार से टकराते हुए दोबारा कोशिश करने के बजाय रुक जाइए।