WhatsApp सर्विस संदेश

सर्विस संदेश वह हर संदेश है जो पहले से स्वीकृत टेम्पलेट नहीं है, यानी वह मुक्त कंटेंट जो कोई व्यवसाय खुली बातचीत के भीतर भेजता है। POST /v1/whatsapp/messages नौ सर्विस-संदेश कंटेंट प्रकारों में से ठीक एक, या एक टेम्पलेट ले जाता है। यह पेज बताता है कि इन नौ प्रकारों में क्या समान है। हर प्रकार का अपना पेज उसकी वायर संरचना और उसकी अपनी सीमाएँ बताता है।

कंटेंट प्रकार

एक अनुरोध में या तो template होता है या इन नौ फ़ील्ड में से ठीक एक। जिस अनुरोध में इनमें से कोई नहीं होता, या एक से ज़्यादा होते हैं, उसे 422 के साथ अस्वीकार कर दिया जाता है।

ग्राहक सेवा विंडो

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

स्वीकार करने से पहले की जाँच के लिए, Bird API सिर्फ़ आने वाले संदेशों के आधार पर विंडो को ट्रैक करता है। कॉल से Meta की विंडो खुल सकती है, जबकि Bird की ट्रैक की गई विंडो बंद रहती है। Bird के ज़रिए मुक्त-रूप सामग्री भेजने से पहले, संपर्क से उस कनेक्ट किए गए बिज़नेस नंबर पर संदेश भेजने के लिए कहें जिसे आप from के तौर पर इस्तेमाल करेंगे। जवाब देते समय आने वाले संदेश के from को प्राप्तकर्ता और उसके to को प्रेषक के तौर पर इस्तेमाल करें। अगर आने वाले संदेश में सिर्फ़ bsuid है, तो उसी ID पर भेजें; कहीं और से मिला फ़ोन नंबर उस विंडो को साझा नहीं करता।

Bird की ट्रैक की गई विंडो बंद होने पर भेजा गया सर्विस संदेश शुरुआत में ही अस्वीकार कर दिया जाता है: अनुरोध 422 E15044 WhatsAppServiceWindowClosed लौटाता है, और न कुछ बनाया जाता है न कोई शुल्क लगता है। इसके बजाय कोई पात्र स्वीकृत टेम्पलेट भेजें; टेम्पलेट के लिए खुली विंडो ज़रूरी नहीं है, और संपर्क का जवाब उसे फिर से खोल देता है। अगर विंडो स्वीकार करने और डिस्पैच के बीच बंद हो जाती है, तो संदेश फिर भी विफल होता है, लेकिन एसिंक्रोनस रूप से: संदेश last_error पर service_window_expired के साथ failed तक पहुँचता है।

अगर API अपनी सर्विस-विंडो जाँच पूरी नहीं कर सकता, तो अनुरोध फिर भी स्वीकार किया जा सकता है ताकि WhatsApp डिस्पैच के समय उसका मूल्यांकन करे। पूरी हुई जाँच में खुली विंडो न मिलने पर अनुरोध अस्वीकार होता है। 202 स्वीकार किए जाने की पुष्टि करता है; डिलीवरी का नतीजा जानने के लिए संदेश की स्थिति देखें।

हर सर्विस संदेश के लिए from भी ज़रूरी है, यानी ऐसा नंबर जो आपके वर्कस्पेस का हो। Bird के मैनेज्ड नंबर इसे नहीं भेज सकते, इसलिए सर्विस संदेश भेजने से पहले आपको अपना नंबर कनेक्ट करना होगा; देखें फ़ोन नंबर सेटअप।

पूरे जीवनचक्र के लिए कस्टमर सर्विस विंडो देखें: विंडो कैसे खुलती है, उसे क्या रीसेट करता है, और उसे कैसे ट्रैक किया जाता है।

URL से मीडिया भेजना

image, video, audio, sticker और document सभी एक url लेते हैं, जो उस फ़ाइल की ओर इशारा करता है जिसे WhatsApp भेजते समय फ़ेच करता है; आपको Bird पर फ़ाइल अपलोड नहीं करनी होती। Bird स्वीकार के समय, कुछ भी कतार में डालने से पहले, URL का स्वरूप जाँचता है:

• खाली न हो और पार्स किया जा सके, उसमें होस्ट हो और कोई कच्चा स्पेस न हो
• स्कीम https हो

http URL को स्वीकार के समय 422 के साथ अस्वीकार कर दिया जाता है, भले ही WhatsApp खुद उसे ठीक से फ़ेच कर लेता। यह Bird की नीति है, WhatsApp की लगाई गई सीमा नहीं।

Bird फ़ाइल का आकार, उसका MIME प्रकार या URL तक पहुँच संभव है या नहीं, यह नहीं जाँचता। WhatsApp संदेश डिस्पैच करने के बाद URL को खुद फ़ेच करता है, इसलिए साइन किया गया URL केवल अनुरोध भेजते समय नहीं, बल्कि उस पल के बाद भी मान्य रहना चाहिए; निजी या समाप्त URL तब विफल होता है जब WhatsApp उसे फ़ेच करने की कोशिश करता है। WhatsApp फ़ेच किए गए URL को लगभग 10 मिनट तक कैश भी करता है, इसलिए उस अवधि में वही URL दोबारा भेजने पर नया फ़ेच नहीं होता, बल्कि पहले फ़ेच का परिणाम ही दिया जाता है।

जब मीडिया विफल होता है

मीडिया भेजना किसी भी WhatsApp संदेश की तरह उसी एसिंक्रोनस रास्ते पर चलता है: Bird 202 लौटाता है और संदेश स्वीकार करता है, फिर डिस्पैच करते समय WhatsApp URL फ़ेच करता है। अगर वह फ़ेच विफल होता है, तो संदेश last_error पर media_rejected के साथ failed तक पहुँचता है, जो अंदर से Meta का 131053 है।

media_rejected एक व्यापक कोड है, जो बहुत बड़ी फ़ाइल, 404, DNS विफलता और गलत MIME टाइप, सभी पर समान रूप से लागू होता है। Bird इसे आगे नहीं बाँटता, इसलिए हर कारण के लिए अलग कोड की अपेक्षा न करें।

असिंक्रोनस रूप से विफल हुए मीडिया संदेश का भी शुल्क लगता है। शुल्क तब लगता है जब Bird स्वीकार किए गए संदेश को प्रोसेस करता है, यानी WhatsApp के URL फ़ेच करने से पहले। शुल्क लगने के बाद रिफ़ंड का कोई रास्ता नहीं है। इसलिए बजट इसी हिसाब से बनाएँ: जो संदेश बाद में media_rejected में विफल होता है, उसकी लागत डिलीवर हुए संदेश जितनी ही होती है।

संपर्क द्वारा भेजा गया संदेश पढ़ना

इनबाउंड संदेश में भी इन्हीं नौ आर्म में से एक होता है, इसलिए आप वही फ़ील्ड पढ़ते हैं जो संपर्क द्वारा इस्तेमाल किए गए टाइप से मेल खाता है। संपर्क कार्ड उसी contact_cards फ़ील्ड में पढ़े जाते हैं, चाहे संपर्क ने कार्ड साझा किया हो या आपने भेजा हो। WhatsApp संदेश प्राप्त करना में API के ज़रिए इनबाउंड संदेश पढ़ने, संपर्क द्वारा भेजा गया मीडिया फ़ेच करने और whatsapp.received वेबहुक की जानकारी है।

अगले कदम

• WhatsApp संदेश भेजना: अनुरोध का ढाँचा, 202 मॉडल और सुरक्षित रूप से फिर से प्रयास करना
• इंटरैक्टिव संदेश: छह टाइप, जिन पर प्राप्तकर्ता टैप कर सकता है
• WhatsApp संदेश प्राप्त करना: इनबाउंड संदेश, मीडिया और whatsapp.received वेबहुक
• WhatsApp टेम्पलेट: वे संदेश जिन्हें आप विंडो बंद होने के बाद भी भेज सकते हैं