Spun आपको उसी नंबर पर एक REST API देता है जिस पर आपकी टीम अपने शेयर्ड WhatsApp इनबॉक्स में जवाब देती है: टेक्स्ट और मीडिया भेजें, मैसेज पढ़ें, कॉन्टैक्ट और लेबल अपडेट करें, और वेबहुक्स सब्सक्राइब करें। यह उस नंबर के सामने काम करता है जिसे आपने QR स्कैन से लिंक किया है, इसलिए इसके लिए Business API की ज़रूरत नहीं होती और कोई प्रति मैसेज शुल्क नहीं लगता।
WhatsApp API से जो काम करवाए जाते हैं, उनमें से ज़्यादातर चार चीज़ों पर आकर रुकते हैं: मैसेज भेजना, कुछ खोजना, कोई रिकॉर्ड बदलना, और कुछ होने पर सूचना पाना। Spun ये चारों काम सादे HTTP पर उसी नंबर के लिए देता है जिस पर आपकी टीम इनबॉक्स में जवाब देती है, और ऑथेंटिकेशन उस कुंजी से होता है जिसे आप खुद बनाते हैं और ठीक उतने स्कोप तक सीमित करते हैं जितने की इंटीग्रेशन को ज़रूरत है।
यह पेज इसका व्यावहारिक रूप है: एंडपॉइंट कौन-से हैं, ऑथेंटिकेशन और स्कोप कैसे काम करते हैं, कॉल करते समय अगर आपकी WhatsApp लाइन ऑफलाइन हो तो क्या होता है, और मशीन से पढ़ा जा सकने वाला कॉन्ट्रैक्ट कहां मिलता है।
कुंजियां, स्कोप और लीक होने पर नुकसान का दायरा
ऑथेंटिकेशन एक bearer टोकन से होता है। आप ऐप में एक कुंजी बनाते हैं, वह आपको सिर्फ़ एक बार दिखाई जाती है, और हर रिक्वेस्ट उसे Authorization हेडर में साथ लेकर जाती है। Spun कुंजी का सिर्फ़ एक हैश स्टोर करता है, इसलिए खोई हुई कुंजी वापस नहीं मिल सकती, उसे सिर्फ़ बदला जा सकता है।
जिस हिस्से पर एक मिनट देना फ़ायदेमंद है, वह है स्कोपिंग। कुंजी का मतलब सिर्फ़ "अकाउंट का एक्सेस" नहीं है: उसके साथ स्कोप की एक लिस्ट होती है, और हर एंडपॉइंट अपने लिए ज़रूरी खास स्कोप की जांच करता है। सिर्फ़ read_contacts वाली कुंजी मैसेज नहीं भेज सकती। सिर्फ़ send_message वाली कुंजी आपकी कॉन्टैक्ट लिस्ट को एक-एक करके नहीं निकाल सकती। स्कोप के अलावा, कुंजी पर एक्सपायरी डेट और IP अलाउलिस्ट भी लगाई जा सकती है, ताकि किसी तय पते वाले सर्वर को दी गई कुंजी जैसे ही कहीं और से इस्तेमाल हो, उसी पल काम करना बंद कर दे।
- send_message में टेक्स्ट और मीडिया भेजना, और कतार में रखे गए सेंड को वापस पढ़ना शामिल है।
- read_contacts, read_messages और read_labels पढ़ने वाला हिस्सा हैं, और इन्हें अलग-अलग दिया जा सकता है।
- manage_contacts और manage_labels में बनाना, अपडेट करना और लेबल लगाना शामिल है।
- check_phone बताता है कि किसी नंबर तक WhatsApp पर पहुंचा जा सकता है या नहीं।
- manage_webhooks वेबहुक सब्सक्रिप्शन बनाता है, उनकी लिस्ट दिखाता है और उन्हें डिलीट करता है।
रिक्वेस्ट
curl -X POST https://api.spun.com/api/integrations/send-message \
-H "Authorization: Bearer wap_0f3c9a1d7b524e86a1c05d9e2f7b48ac" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550142",
"text": "Your appointment is confirmed for Thursday at 10:00.",
"idempotency_key": "booking-8871"
}'रिस्पॉन्स
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"message_id": "yq0Zt9C1sK2mfE7x"
}Spun MCP सर्वर के लिए बनाई गई कुंजियां इस API पर जान-बूझकर ठुकरा दी जाती हैं, भले ही वे वैध कुंजियां हों। दोनों इंटरफ़ेस में अप्रूवल के नियम अलग हैं, और एक के लिए जारी की गई कुंजी चुपचाप दूसरे पर इस्तेमाल नहीं हो सकती।
WhatsApp API के एंडपॉइंट असल में क्या-क्या कवर करते हैं
इंटरफ़ेस जान-बूझकर छोटा और स्थिर रखा गया है, यह प्रोडक्ट की हर चीज़ की पूरी नकल नहीं है। यह इसलिए है ताकि कोई बाहरी सिस्टम वे काम कर सके जो बाहरी सिस्टम को सच में करने होते हैं।
- सेंड: एक टेक्स्ट मैसेज, या URL या base64 के रूप में मीडिया, वैकल्पिक कैप्शन के साथ।
- कॉन्टैक्ट: कॉन्टैक्ट बनाएं, किसी कॉन्टैक्ट को अपडेट करें, और कर्सर पेजिनेशन के साथ कॉन्टैक्ट की लिस्ट देखें।
- लेबल: वर्कस्पेस के लेबल की लिस्ट देखें, किसी बातचीत पर लेबल लगाएं, लेबल हटाएं।
- मैसेज: कर्सर पेजिनेशन के साथ मैसेज की लिस्ट, किसी डेटा वेयरहाउस या CRM में सिंक करने के लिए।
- फ़ोन जांच: किसी नंबर के आधार पर लिस्ट बनाने से पहले पक्का करें कि वह WhatsApp पर है।
- कतार: लाइन ऑफलाइन होने की वजह से कतार में रखा गया कोई सेंड देखें।
- वेबहुक्स: सब्सक्रिप्शन बनाएं, उनकी लिस्ट देखें और उन्हें डिलीट करें।
मशीन से पढ़ा जा सकने वाला कॉन्ट्रैक्ट /api/integrations/openapi.json पर पब्लिश है और उसे पढ़ने के लिए किसी कुंजी की ज़रूरत नहीं, इसलिए n8n नोड लिखने वाला, Zapier ऐप बनाने वाला या आपका अपना जनरेटर क्रेडेंशियल जारी होने से पहले ही स्पेक ले सकता है।
जब WhatsApp लाइन ऑफलाइन हो तो क्या होता है
यही हिस्सा लोगों को हैरान करता है, इसलिए इसे साफ़-साफ़ बताना ज़रूरी है। Spun एक लाइव WhatsApp सेशन के ज़रिए भेजता है, और लाइव सेशन ठीक उसी सेकंड बंद हो सकता है जब आपका कोड कॉल करता है। API इसके उलट दिखावा नहीं करता, और जान-बूझकर टेक्स्ट और मीडिया के साथ अलग-अलग बर्ताव करता है।
ऑफलाइन लाइन पर टेक्स्ट भेजने पर एरर के बजाय 202 मिलता है, साथ में एक कतार id। मैसेज रोककर रखा जाता है और लाइन फिर से कनेक्ट होने पर डिलीवर होता है, और आप उसका नतीजा जानने के लिए कतार एंडपॉइंट को पोल कर सकते हैं। ऑफलाइन लाइन पर मीडिया भेजने पर इसके बजाय कॉन्फ़्लिक्ट मिलता है, और कुछ भी नहीं भेजा जाता। यह फ़र्क जान-बूझकर है: कतार मैसेज को टेक्स्ट के रूप में भेजती है, इसलिए कतार में रखी इमेज बिना तस्वीर के सिर्फ़ कैप्शन बनकर पहुंचती। साफ़ तौर पर फ़ेल होना बेहतर नतीजा है, और आगे क्या करना है यह आपका रीट्राई लॉजिक तय करता है।
रेट लिमिट हर कुंजी के लिए 60 रिक्वेस्ट प्रति मिनट है, और हर रिस्पॉन्स पर स्टैंडर्ड रेट-लिमिट हेडर होते हैं, ताकि क्लाइंट किसी अनचाहे 429 के बजाय हेडर देखकर रफ़्तार धीमी कर सके।
वेबहुक्स: पोलिंग के बजाय सूचना पाना
टाइमर पर मैसेज एंडपॉइंट को बार-बार पोल करना बातचीत के लिए सही तरीका नहीं है, इसलिए API खुद पुश कर सकता है। आप एक URL और वे इवेंट्स रजिस्टर करते हैं जो आपके काम के हैं, और जैसे-जैसे वे होते हैं, Spun उस URL पर एक JSON बॉडी पोस्ट करता है।
हर डिलीवरी के हेडर में इवेंट का नाम और एक यूनिक डिलीवरी id होती है, और अगर सब्सक्रिप्शन में साइनिंग सीक्रेट है तो ठीक उसी बॉडी का HMAC-SHA256 सिग्नेचर भी। पेलोड पर भरोसा करने से पहले सिग्नेचर की जांच करें: यही एक चीज़ आपके एंडपॉइंट को हर उस व्यक्ति से अलग करती है जिसे URL पता चल जाए। सीक्रेट सिर्फ़ एक बार, सब्सक्रिप्शन बनाते समय लौटाया जाता है, फिर कभी नहीं।
- मैसेज इवेंट्स, आने वाले और जाने वाले।
- कॉन्टैक्ट बनाया गया, अपडेट किया गया और डिलीट किया गया।
- लेबल असाइन किया गया।
- चैट फ्लो पूरा हुआ, कतार वाला सेंड प्रोसेस हुआ, लीड क्वालिफ़ाई हुई।
- बातचीत बंद हुई, कॉल पूरी हुई, और पाइपलाइन स्टेज बदला।
संबंधित: Spun को Zapier और Make से कनेक्ट करना · Spun को n8n से कनेक्ट करना · हेल्पडेस्क कनेक्ट करना: Zendesk, Zoho Desk, Freshdesk, HubSpot Service Hub, Jira
सीमाएं और ईमानदार चेतावनियां
- यह WhatsApp Business API नहीं है। यह आपके लिंक किए गए नंबर के सामने Spun का अपना API है, इसलिए न कोई मैसेज टेम्प्लेट अप्रूव करवाना होता है, न प्रति मैसेज शुल्क लगता है, और उसी तरह Meta की कोई आधिकारिक गारंटी भी नहीं है।
- हर कुंजी के लिए साठ रिक्वेस्ट प्रति मिनट। बल्क काम कैंपेन में होना चाहिए, जो अपनी रफ़्तार खुद सही तरीके से संभालते हैं, किसी तेज़ API लूप में नहीं।
- ऊपर दी गई एंडपॉइंट लिस्ट ही आज का पूरा इंटरफ़ेस है। जो इसमें नहीं है वह उपलब्ध नहीं है, और किसी भी बिना डॉक्यूमेंटेशन वाले एंडपॉइंट पर भरोसा नहीं करना चाहिए।
- कुंजी स्कोप वाली होती है, लेकिन हर यूज़र के लिए अलग नहीं। इसे वर्कस्पेस के क्रेडेंशियल की तरह समझें और जब एक्सेस वाला कोई व्यक्ति चला जाए तो इसे बदल दें।
- जिन लोगों ने कभी सहमति नहीं दी, उन्हें मैसेज भेजने पर WhatsApp नंबर को सीमित कर देगा, चाहे मैसेज किसी भी रास्ते से गया हो।
संबंधित: Spun WhatsApp से कैसे कनेक्ट होता है