टेलीग्राम बॉट वेबहुक सेटअप: डेवलपर्स के लिए संपूर्ण मार्गदर्शिका

टेलीग्राम बॉट वेबहुक सेटअप आपके सर्वर को टेलीग्राम के अपडेट स्ट्रीम से जोड़ता है ताकि संदेश पोलिंग लूप के बजाय वास्तविक समय में आएं। यदि आप बॉट एपीआई के साथ एक कस्टम बॉट बना रहे हैं, तो वेबहुक मानक उत्पादन पथ हैं: टेलीग्राम प्रत्येक अपडेट को आपके HTTPS एंडपॉइंट पर POST करता है, और आपका कोड प्रतिक्रिया देता है।

यह मार्गदर्शिका पूर्वापेक्षाओं, पंजीकरण, एक कार्यशील हैंडलर उदाहरण, सत्यापन, समस्या निवारण, और जब TeleClaw जैसे प्रबंधित प्लेटफ़ॉर्म स्वयं-होस्टिंग से अधिक समझ में आता है, के बारे में बताती है।

मुख्य बातें

• वेबहुक और लॉन्ग पोलिंग परस्पर अनन्य हैं। एक वेबहुक सेट करने से getUpdates तब तक अक्षम हो जाता है जब तक आप इसे हटा नहीं देते।
• HTTPS अनिवार्य है। आपके एंडपॉइंट को TLS 1.2+, एक मिलान प्रमाणपत्र, और पोर्ट 443, 80, 88, या 8443 की आवश्यकता है।
• setWebhook के साथ पंजीकृत करें, getWebhookInfo के साथ सत्यापित करें। जब अपडेट आना बंद हो जाए तो last_error_message की जांच करें।
• secret_token का उपयोग करें यह पुष्टि करने के लिए कि अनुरोध टेलीग्राम से आते हैं, न कि आपके URL पर हिट करने वाले यादृच्छिक स्कैनर से।
• नो-कोड विकल्प: TeleClaw होस्टिंग और डिलीवरी को संभालता है ताकि आप सर्वर परत को पूरी तरह से छोड़ सकें।

वेबहुक बनाम लॉन्ग पोलिंग: किसे चुनें

टेलीग्राम अपडेट प्राप्त करने के दो तरीके प्रदान करता है। बॉट्स FAQ के अनुसार, आप प्रति बॉट एक विधि चुनते हैं। आप एक ही समय में दोनों को नहीं चला सकते।

लॉन्ग पोलिंग प्रोटोटाइप बनाने का सबसे तेज़ तरीका है। आपका बॉट एक लूप में getUpdates को कॉल करता है, प्रत्येक बैच को संसाधित करता है, और ऑफ़सेट को आगे बढ़ाता है। कोई डोमेन नहीं, कोई प्रमाणपत्र नहीं, कोई खुला पोर्ट नहीं।

वेबहुक मॉडल को पलट देते हैं। जब भी कोई बॉट को संदेश भेजता है तो टेलीग्राम आपके URL पर एक HTTPS POST भेजता है। यह निष्क्रिय पोलिंग अनुरोधों को हटाता है और प्रतिक्रिया समय को कम करता है, जो समर्थन बॉट्स, भुगतान प्रवाह और बड़े पैमाने पर समूह मॉडरेशन के लिए मायने रखता है।

यदि आप अभी भी बॉट को स्वयं पंजीकृत कर रहे हैं, तो यहां जारी रखने से पहले BotFather से टोकन प्राप्त करने के लिए टेलीग्राम बॉट बनाने के लिए हमारी मार्गदर्शिका से शुरू करें।

टेलीग्राम बॉट वेबहुक सेटअप के लिए पूर्वापेक्षाएँ

setWebhook को कॉल करने से पहले, पुष्टि करें कि आपका बुनियादी ढांचा आधिकारिक वेबहुक मार्गदर्शिका से टेलीग्राम की आवश्यकताओं को पूरा करता है:

• @BotFather से बॉट टोकन (ऊपर लिंक की गई क्रिएट-बॉट मार्गदर्शिका देखें)।
• एक वैध TLS प्रमाणपत्र के साथ सार्वजनिक डोमेन। स्व-हस्ताक्षरित प्रमाणपत्र तभी काम करते हैं जब आप certificate पैरामीटर के माध्यम से सार्वजनिक कुंजी अपलोड करते हैं।
• आपके सर्वर पर समर्थित पोर्ट: 443 (डिफ़ॉल्ट), 80, 88, या 8443। अन्य पोर्ट अस्वीकृत हैं।
• प्रमाणपत्र CN या SAN आपके वेबहुक URL में डोमेन से मेल खाना चाहिए। वाइल्डकार्ड प्रमाणपत्र काम नहीं कर सकते हैं। रीडायरेक्ट समर्थित नहीं हैं।
• टेलीग्राम सबनेट 149.154.160.0/20 और 91.108.4.0/22 से इनबाउंड POST एक्सेस।

स्थानीय विकास के लिए, एक टनल (ngrok, Cloudflare Tunnel, या इसी तरह) के माध्यम से लोकलहोस्ट को उजागर करें जो आपको एक सार्वजनिक HTTPS URL देता है। वेबहुक को पंजीकृत करने से पहले परीक्षण करें कि टनल POST अनुरोधों के लिए HTTP 200 लौटाता है।

चरण 1: अपना वेबहुक एंडपॉइंट बनाएं

आपके सर्वर को एक मार्ग की आवश्यकता है जो POST अनुरोधों को स्वीकार करता है, JSON Update ऑब्जेक्ट को पार्स करता है, और HTTP 200 को जल्दी से लौटाता है। धीमे हैंडलर टेलीग्राम को पुनः प्रयास करने और अंततः getWebhookInfo में त्रुटियों की रिपोर्ट करने का कारण बनते हैं।

एक्सप्रेस के साथ न्यूनतम Node.js उदाहरण:

import express from 'express';

const app = express();
app.use(express.json());

const SECRET = process.env. WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
 if (SECRET && req.get('X-Telegram-Bot-Api-Secret-Token')!== SECRET) {
 return res.sendStatus(403);
 }

 const update = req.body;
 // Process update.message, update.callback_query, etc.
 console.log('Update ID:', update.update_id);

 res.sendStatus(200);
});

app.listen(443);

Flask के साथ Python उसी पैटर्न का पालन करता है: request से JSON पढ़ें, यदि कॉन्फ़िगर किया गया हो तो गुप्त हेडर को मान्य करें, अपडेट को संसाधित करें, 200 लौटाएं।

तेजी से प्रतिक्रिया दें। भारी काम (डेटाबेस लेखन, AI API कॉल) को पृष्ठभूमि कतार में जाना चाहिए। टेलीग्राम एक त्वरित पावती की उम्मीद करता है। आप एक अलग API कॉल करने के बजाय method फ़ील्ड के साथ एक JSON बॉडी लौटाकर इनलाइन भी जवाब दे सकते हैं, जैसा कि बॉट एपीआई वेबहुक नोट्स में वर्णित है।

चरण 2: setWebhook के साथ टेलीग्राम बॉट कॉन्फ़िगर वेबहुक

एक बार जब आपका एंडपॉइंट लाइव हो जाए, तो इसे बॉट एपीआई के साथ पंजीकृत करें। <TOKEN> और URL को अपने मानों से बदलें।

curl का उपयोग करना:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -H "Content-Type: application/json" \
 -d '{
 "url": "https://yourdomain.com/webhook",
 "secret_token": "my_random_secret_abc123",
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"],
 "drop_pending_updates": false
 }'

पैरामीटर संदर्भ:

• url (आवश्यक): आपका HTTPS एंडपॉइंट। वेबहुक को हटाने के लिए एक खाली स्ट्रिंग का उपयोग करें।
• secret_token (वैकल्पिक): 1-256 वर्ण (A-Z, a-z, 0-9, _, -)। टेलीग्राम इसे X-Telegram-Bot-Api-Secret-Token हेडर में भेजता है।
• max_connections (वैकल्पिक): 1-100 एक साथ कनेक्शन। डिफ़ॉल्ट 40 है।
• allowed_updates (वैकल्पिक): आप किस प्रकार के अपडेट प्राप्त करते हैं उसे सीमित करें। यदि आप केवल संदेशों को संभालते हैं तो पेलोड आकार कम करता है।
• drop_pending_updates (वैकल्पिक): वेबहुक स्विच करते समय कतारबद्ध अपडेट को छोड़ने के लिए true सेट करें।
• certificate (वैकल्पिक): स्व-हस्ताक्षरित प्रमाणपत्रों के लिए अपनी सार्वजनिक कुंजी फ़ाइल अपलोड करें।

एक सफल प्रतिक्रिया {"ok":true,"result":true,"description":"Webhook was set"} जैसी दिखती है।

चरण 3: getWebhookInfo के साथ सत्यापित करें

हमेशा तुरंत पंजीकरण की पुष्टि करें। जब अपडेट आना बंद हो जाए तो यह आपका पहला समस्या निवारण उपकरण है।

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

उदाहरण प्रतिक्रिया:

{
 "ok": true,
 "result": {
 "url": "https://yourdomain.com/webhook",
 "has_custom_certificate": false,
 "pending_update_count": 0,
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"]
 }
}

इन फ़ील्ड्स को देखें:

• url: खाली का मतलब है कि कोई वेबहुक सक्रिय नहीं है (बॉट लॉन्ग पोलिंग पर है)।
• pending_update_count: डिलीवरी की प्रतीक्षा कर रहे कतारबद्ध अपडेट। बढ़ती संख्या डिलीवरी विफलताओं का संकेत देती है।
• last_error_date और last_error_message: सबसे हालिया विफलता का कारण। मूल कारण को ठीक करें, फिर टेलीग्राम स्वचालित रूप से पुनः प्रयास करता है।
• ip_address: कौन सा टेलीग्राम IP वर्तमान में आपके एंडपॉइंट पर हिट कर रहा है।

अपने बॉट को एक वास्तविक टेलीग्राम खाते से एक परीक्षण संदेश भेजें। यदि pending_update_count शून्य पर रहता है और आपके सर्वर लॉग POST दिखाते हैं, तो टेलीग्राम बॉट वेबहुक सेटअप काम कर रहा है।

टेलीग्राम बॉट वेबहुक उदाहरण: जॉइन रिक्वेस्ट हैंडलर

जॉइन-रिक्वेस्ट बॉट्स (गार्जियन-शैली प्रवेश प्रवाह) को chat_join_request अपडेट प्रकार की आवश्यकता होती है। हमारी गार्जियन बॉट मार्गदर्शिका उत्पाद पक्ष को कवर करती है। यहां वेबहुक वायरिंग है।

जॉइन अनुरोध सक्षम के साथ पंजीकृत करें:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -d "url=https://yourdomain.com/webhook" \
 -d "allowed_updates=[\"chat_join_request\",\"message\"]"

हैंडलर लॉजिक (छद्मकोड):

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // स्क्रीनिंग लॉजिक चलाएं, फिर बॉट एपीआई के माध्यम से स्वीकृत या अस्वीकृत करें
 await approveChatJoinRequest(chat.id, from.id);
}

टेलीग्राम जॉइन अनुरोधों को पुश अपडेट के रूप में वितरित करता है, इसलिए वेबहुक प्रवेश बॉट्स के लिए एक स्वाभाविक फिट हैं जिन्हें अनुरोध समाप्त होने से पहले प्रतिक्रिया देनी होगी।

टेलीग्राम बॉट वेबहुक हटाएँ और पोलिंग पर वापस स्विच करें

getUpdates के साथ स्थानीय रूप से डीबग करने की आवश्यकता है? पहले वेबहुक हटा दें।

deleteWebhook के साथ विकल्प A:

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
 -d "drop_pending_updates=true"

setWebhook और खाली URL के साथ विकल्प B:

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url="

दोनों विधियाँ लॉन्ग पोलिंग को फिर से सक्षम करती हैं। यदि आप इस चरण को छोड़ देते हैं, तो getUpdates कुछ भी नहीं लौटाता है क्योंकि वेबहुक अभी भी आपके उत्पादन URL पर पंजीकृत है।

सामान्य वेबहुक त्रुटियों का निवारण

जब getWebhookInfo त्रुटियां दिखाता है, तो संदेश को एक समाधान से मिलाएं:

उत्पादन में एक शेड्यूल पर getWebhookInfo चलाएं। last_error_message को जल्दी पकड़ने से घंटों के मूक संदेश हानि को रोका जा सकता है।

सर्वर को छोड़ें: TeleClaw के साथ प्रबंधित बॉट

हर बॉट को कस्टम वेबहुक बुनियादी ढांचे की आवश्यकता नहीं होती है। यदि आपका लक्ष्य किसी समूह या व्यावसायिक चैनल के लिए एक AI सहायक है, तो होस्टिंग और अपडेट डिलीवरी हल की गई समस्याएं हैं।

TeleClaw आपके BotFather टोकन को OpenClaw द्वारा संचालित एक प्रबंधित रनटाइम से जोड़ता है। आप डैशबोर्ड में व्यक्तित्व, ज्ञान आधार और मॉडरेशन नियमों को कॉन्फ़िगर करते हैं। प्लेटफ़ॉर्म HTTPS एंडपॉइंट्स, स्केलिंग और AI मॉडल रूटिंग को संभालता है। @claw को एक समूह व्यवस्थापक के रूप में जोड़ें और एक वेबहुक हैंडलर लिखे बिना लाइव हो जाएं।

TeleClaw सुविधाओं पृष्ठ पर एक प्रबंधित बॉट क्या कर सकता है, इसका अन्वेषण करें। एक पूर्ण नो-कोड वॉकथ्रू के लिए, हमारी टेलीग्राम चैटबॉट नो-कोड मार्गदर्शिका देखें।

कस्टम वेबहुक अभी भी समझ में आते हैं जब आपको पूर्ण नियंत्रण की आवश्यकता होती है: मालिकाना बैकएंड, विनियमित डेटा निवास, या गैर-मानक अपडेट प्रसंस्करण। बाकी सब के लिए, प्रमाणपत्र प्रबंधन, निगरानी और पुनः प्रयास हैंडलिंग की परिचालन लागत तेजी से बढ़ती है।

निष्कर्ष

टेलीग्राम बॉट वेबहुक सेटअप चार चरणों में आता है: एक HTTPS एंडपॉइंट डिप्लॉय करें, setWebhook को कॉल करें, getWebhookInfo के साथ सत्यापित करें, और त्रुटियों के लिए मॉनिटर करें। अनुरोध सत्यापन के लिए secret_token का उपयोग करें, allowed_updates को सीमित करें जो आप संसाधित करते हैं, और हैंडलर को तेज़ रखें।

जो डेवलपर्स सर्वर चलाए बिना उत्पादन पुश डिलीवरी चाहते हैं, वे इसके बजाय TeleClaw का उपयोग कर सकते हैं। अपना टोकन पेस्ट करें, AI व्यवहार को कॉन्फ़िगर करें, और इस बात पर ध्यान केंद्रित करें कि बॉट क्या कहता है बजाय इसके कि अपडेट कैसे आते हैं।

वेबहुक प्रबंधित किए बिना एक AI बॉट लॉन्च करने के लिए तैयार हैं? अपने टेलीग्राम समूह में @claw जोड़ें →