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

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

यदि आपने कभी टेलीग्राम बॉट बनाया है, तो आपने लगभग निश्चित रूप से दो शब्दों का सामना किया होगा: पोलिंग (polling) और वेबहुक्स (webhooks)। पोलिंग एक आसान शुरुआती बिंदु है — आपका कोड लूप करता है और टेलीग्राम से हर सेकंड “कोई नया संदेश है?” पूछता है — लेकिन यह अच्छी तरह से स्केल नहीं करता है और अनावश्यक रूप से संसाधनों को जलाता है। वेबहुक्स इस मॉडल को उलट देते हैं: जब भी कुछ होता है तो टेलीग्राम आपके सर्वर को कॉल करता है, जिससे आपका बॉट तेज़, चलाने में सस्ता और प्रोडक्शन के लिए कहीं अधिक उपयुक्त हो जाता है।

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

मुख्य बातें

• वेबहुक्स पुश हैं, पोलिंग पुल है। वेबहुक्स अनावश्यक API कॉल को समाप्त करते हैं और विलंबता को लगभग शून्य तक कम करते हैं।
• HTTPS अनिवार्य है। टेलीग्राम को आपके एंडपॉइंट पर एक वैध TLS प्रमाणपत्र की आवश्यकता होती है। Let’s Encrypt और Cloudflare इसे मुफ्त और आसान बनाते हैं।
• एक बॉट, एक वेबहुक URL। टेलीग्राम अपडेट को ठीक एक एंडपॉइंट पर डिलीवर करता है। यदि आप एक नया URL पंजीकृत करते हैं, तो पुराना तुरंत अपडेट प्राप्त करना बंद कर देता है।
• जल्दी से 200 लौटाएँ। टेलीग्राम 200 OK के लिए 60 सेकंड तक प्रतीक्षा करता है। यदि आपका एंडपॉइंट टाइम आउट हो जाता है या त्रुटि लौटाता है, तो टेलीग्राम फिर से प्रयास करेगा — यदि आप सावधान नहीं हैं तो डुप्लिकेट प्रोसेसिंग हो सकती है।
• TeleClaw यह सब स्वचालित करता है। प्रबंधित प्लेटफ़ॉर्म वेबहुक पंजीकरण, TLS, और पुन: प्रयास तर्क को संभालते हैं, ताकि आप पाइपलाइन के बजाय तर्क लिख सकें।

टेलीग्राम बॉट वेबहुक्स कैसे काम करते हैं

जब कोई उपयोगकर्ता आपके बॉट को संदेश भेजता है, तो टेलीग्राम का इंफ्रास्ट्रक्चर इसे प्राप्त करता है और तुरंत आपके पंजीकृत वेबहुक URL पर एक HTTP POST अनुरोध भेजता है। अनुरोध बॉडी एक JSON-एन्कोडेड Update object होती है, जिसमें एक संदेश, एक संपादित संदेश, एक इनलाइन कीबोर्ड से कॉलबैक क्वेरी, एक भुगतान, और बहुत कुछ हो सकता है।

आपके सर्वर को चाहिए:

1. आने वाले JSON को पार्स करें।
2. अपडेट प्रकार निर्धारित करें और इसे उपयुक्त हैंडलर पर रूट करें।
3. HTTP 200 OK के साथ प्रतिक्रिया दें (बॉडी खाली या एक साधारण API उत्तर हो सकती है)।
4. वैकल्पिक रूप से उत्तर भेजने या अन्य कार्रवाई करने के लिए टेलीग्राम बॉट API को कॉल करें।

सरल प्रतिक्रियाओं के लिए पूरी राउंड-ट्रिप आमतौर पर 100 मिलीसेकंड से कम में पूरी हो जाती है, जिससे उपयोगकर्ताओं को लगभग तत्काल अनुभव मिलता है।

अपडेट ऑब्जेक्ट

प्रत्येक वेबहुक पेलोड update_id से शुरू होता है — एक मोनोटोनिक रूप से बढ़ता हुआ पूर्णांक जिसका उपयोग आप डुप्लिकेट का पता लगाने के लिए कर सकते हैं — जिसके बाद इवेंट प्रकार का वर्णन करने वाला ठीक एक वैकल्पिक फ़ील्ड होता है:

यह समझना कि कौन सा फ़ील्ड मौजूद है, आपको पूरे पेलोड को पार्स किए बिना अपडेट को सही हैंडलर पर रूट करने देता है।

टेलीग्राम बॉट वेबहुक सेट करना: चरण-दर-चरण

चरण 1: अपना बॉट टोकन प्राप्त करें

यदि आपने अभी तक बॉट नहीं बनाया है, तो टेलीग्राम पर BotFather खोलें और /newbot भेजें। अपने बॉट का नाम देने और 123456789:ABCdef... प्रारूप में एक टोकन प्राप्त करने के लिए संकेतों का पालन करें। इस टोकन को गुप्त रखें — जिसके पास भी यह है वह आपके बॉट का प्रतिरूपण कर सकता है।

चरण 2: एक HTTPS एंडपॉइंट तैयार करें

टेलीग्राम के सर्वर आपके URL पर अपडेट POST करेंगे, इसलिए इसे पोर्ट 443, 80, 88, या 8443 पर HTTPS पर सार्वजनिक रूप से पहुंच योग्य होना चाहिए। व्यवहार में, अधिकांश डेवलपर पोर्ट 443 का उपयोग करते हैं।

एक वैध TLS प्रमाणपत्र प्राप्त करने के लिए आपके विकल्प:

• Let’s Encrypt — मुफ्त, व्यापक रूप से विश्वसनीय, Certbot या समान टूल के माध्यम से स्वतः-नवीकरणीय।
• Cloudflare Proxy — अपने मूल को Cloudflare के पीछे रखें और मुफ्त में TLS समाप्ति प्राप्त करें। टेलीग्राम की IP श्रेणियां बिना किसी विशेष कॉन्फ़िगरेशन के Cloudflare के किनारे तक पहुंच सकती हैं।
• TeleClaw जैसे प्रबंधित प्लेटफ़ॉर्म — यदि आप TeleClaw के माध्यम से अपना बॉट तैनात करते हैं, तो प्लेटफ़ॉर्म स्वचालित रूप से एक सुरक्षित HTTPS एंडपॉइंट प्रदान करता है। किसी प्रमाणपत्र प्रबंधन की आवश्यकता नहीं है।
• सेल्फ-साइन किया गया प्रमाणपत्र — टेलीग्राम द्वारा तकनीकी रूप से समर्थित, लेकिन आपको setWebhook को कॉल करते समय .pem फ़ाइल अपलोड करनी होगी। प्रोडक्शन में इससे बचें; यह जटिलता बढ़ाता है और ब्राउज़र द्वारा विश्वसनीय नहीं है।

चरण 3: वेबहुक पंजीकृत करें

एक साधारण HTTPS GET या POST अनुरोध का उपयोग करके, या किसी भी टेलीग्राम बॉट API लाइब्रेरी के माध्यम से setWebhook विधि को कॉल करें:

https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://yourdomain.com/webhook/<TOKEN>

आपके टोकन को पथ में शामिल करना (उदाहरण के लिए, /webhook/123456789:ABCdef) एक सामान्य सुरक्षा पैटर्न है — यह एक साझा रहस्य के रूप में कार्य करता है, यह सुनिश्चित करता है कि केवल टेलीग्राम ही आपके एंडपॉइंट को ट्रिगर कर सकता है। इस URL को हमेशा निजी रखें।

अतिरिक्त उपयोगी पैरामीटर:

secret_token पैरामीटर (बॉट API 6.0 के बाद से उपलब्ध) विशेष रूप से उपयोगी है। जब सेट किया जाता है, तो टेलीग्राम प्रत्येक डिलीवरी पर एक X-Telegram-Bot-Api-Secret-Token हेडर शामिल करता है। आपका एंडपॉइंट पेलोड को संसाधित करने से पहले इस हेडर को मान्य कर सकता है, स्पूफ किए गए अनुरोधों से बचाव कर सकता है।

चरण 4: पंजीकरण सत्यापित करें

सब कुछ सही ढंग से कॉन्फ़िगर किया गया है यह पुष्टि करने के लिए getWebhookInfo को कॉल करें:

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

एक सफल प्रतिक्रिया इस तरह दिखती है:

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

यदि last_error_message में कुछ भी है, तो वह आपका पहला डिबगिंग सुराग है।

चरण 5: अपना हैंडलर लिखें और तैनात करें

यहां Flask का उपयोग करके Python में एक न्यूनतम वेबहुक हैंडलर का उदाहरण दिया गया है:

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
BOT_TOKEN = "YOUR_TOKEN"
SECRET_TOKEN = "YOUR_SECRET_TOKEN"

@app.route(f"/webhook/{BOT_TOKEN}", methods=["POST"])
def webhook():
    # Validate secret token
    incoming = request.headers.get("X-Telegram-Bot-Api-Secret-Token", "")
    if not hmac.compare_digest(incoming, SECRET_TOKEN):
        return jsonify({"error": "Unauthorized"}), 403

    update = request.get_json()
    if update.get("message"):
        chat_id = update["message"]["chat"]["id"]
        text = update["message"].get("text", "")
        # ... handle the message
    return "", 200  # Always respond 200 quickly

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=443)

महत्वपूर्ण नियम: जितनी जल्दी हो सके 200 लौटाएँ। यदि आपकी प्रोसेसिंग धीमी है (एक LLM को कॉल करना, एक डेटाबेस से क्वेरी करना), तो इसे एक पृष्ठभूमि कतार में ऑफलोड करें और तुरंत प्रतिक्रिया दें। टेलीग्राम किसी भी अपडेट को फिर से प्रयास करेगा जिसे 60 सेकंड के भीतर 200 प्राप्त नहीं होता है, और पुन: प्रयास 25 सेकंड के अंतराल तक घातीय बैक-ऑफ का पालन करते हैं, जो 24 घंटे तक जारी रहते हैं।

सामान्य वेबहुक त्रुटियाँ और उन्हें कैसे ठीक करें

”वेबहुक से गलत प्रतिक्रिया: 403 Forbidden”

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

“SSL हैंडशेक विफल”

आपका TLS प्रमाणपत्र समाप्त हो गया है, अपलोड किए बिना सेल्फ-साइन किया गया है, या एक सिफर सूट का उपयोग कर रहा है जिसे टेलीग्राम समर्थन नहीं करता है। टेलीग्राम को TLS 1.2 या उच्चतर की आवश्यकता है। अपना प्रमाणपत्र नवीनीकृत करें, या Cloudflare जैसे CDN पर स्विच करें जो TLS को स्वचालित रूप से संभालता है।

अपडेट आते हैं लेकिन डुप्लिकेट दिखाई देते हैं

आप 200 लौटाने में 60 सेकंड से अधिक समय ले रहे हैं, इसलिए टेलीग्राम फिर से प्रयास करता है। भारी प्रोसेसिंग को एक पृष्ठभूमि कार्यकर्ता पर ले जाएँ और तुरंत प्रतिक्रिया दें। साथ ही, प्रोसेसिंग से पहले एक कैश या डेटाबेस के खिलाफ update_id की जाँच करके अपने हैंडलर को आइडम्पोटेंट (idempotent) बनाएँ।

“वेबहुक सेट किया गया था, लेकिन कोई अपडेट नहीं आता है”

जाँच करें कि क्या किसी अन्य प्रक्रिया या परिनियोजन ने आपके वेबहुक पंजीकरण को अधिलेखित कर दिया है। वर्तमान URL देखने के लिए getWebhookInfo को कॉल करें। यह भी पुष्टि करें कि allowed_updates उस अपडेट प्रकार को फ़िल्टर नहीं कर रहा है जिसकी आप अपेक्षा करते हैं — यदि allowed_updates message को छोड़ देता है, तो आपको कभी भी सादे संदेश प्राप्त नहीं होंगे।

वेबहुक इंफ्रास्ट्रक्चर को स्केल करना

कम-ट्रैफिक वाले बॉट्स के लिए, एक सिंगल सर्वर सब कुछ संभालता है। जैसे-जैसे आपका उपयोगकर्ता आधार बढ़ता है, आपको नई चुनौतियों का सामना करना पड़ेगा।

क्षैतिज स्केलिंग (Horizontal scaling) वेबहुक्स के साथ सीधी है: लोड बैलेंसर के पीछे अपने हैंडलर के कई उदाहरण चलाएँ। क्योंकि टेलीग्राम का max_connections पैरामीटर नियंत्रित करता है कि टेलीग्राम आपके एंडपॉइंट पर कितने समवर्ती कनेक्शन खोलता है, आप इसे अपनी क्षमता से मेल खाने के लिए ट्यून कर सकते हैं। इसे बहुत अधिक सेट करें और आप एक सिंगल सर्वर को ओवरलोड कर देंगे; इसे बहुत कम सेट करें और अपडेट टेलीग्राम की तरफ कतारबद्ध हो जाएंगे।

कतार-आधारित प्रोसेसिंग (Queue-based processing) अपडेट प्राप्त करने को उन पर कार्य करने से अलग करती है। आपका वेबहुक हैंडलर प्रत्येक Update को एक संदेश कतार (Redis, RabbitMQ, SQS) में डालता है, तुरंत 200 प्रतिक्रिया देता है, और कार्यकर्ता प्रक्रियाओं का एक पूल अपनी गति से आइटम उठाता है। यह पैटर्न टाइमआउट को पूरी तरह से रोकता है और आपको वेबहुक रिसीवर से स्वतंत्र रूप से कार्यकर्ताओं को स्केल करने देता है।

आइडम्पोटेंसी (Idempotency) पैमाने पर आवश्यक हो जाती है। Redis जैसे तेज़ कुंजी-मूल्य स्टोर में संसाधित update_id मानों को स्टोर करें और किसी भी अपडेट को छोड़ दें जिसे आपने पहले ही संभाल लिया है। परमाणु संचालन के साथ संयुक्त, यह डुप्लिकेट उत्तरों को रोकता है, भले ही पुन: प्रयास होते हों।

भौगोलिक वितरण (Geographic distribution) वैश्विक उपयोगकर्ता आधारों के लिए विलंबता को कम कर सकता है। कई क्षेत्रों में वेबहुक रिसीवर तैनात करें और टेलीग्राम की डिलीवरी को निकटतम एंडपॉइंट पर निर्देशित करने के लिए DNS-आधारित रूटिंग या एक वैश्विक CDN का उपयोग करें।

TeleClaw यह सब क्यों सरल बनाता है

वेबहुक इंफ्रास्ट्रक्चर का प्रबंधन — TLS प्रमाणपत्र, लोड बैलेंसर, पुन: प्रयास हैंडलिंग, IP अनुमति सूची — एक अविभेदित भारी लिफ्टिंग है। TeleClaw इसे पूरी तरह से समाप्त कर देता है।

जब आप अपने बॉट टोकन को TeleClaw से जोड़ते हैं:

• स्वचालित वेबहुक पंजीकरण। TeleClaw आपके बॉट के लिए एक सुरक्षित, टेलीग्राम-अनुरूप HTTPS एंडपॉइंट पंजीकृत करता है। आप कभी भी setWebhook को मैन्युअल रूप से नहीं छूते हैं।
• अंतर्निहित TLS। सभी एंडपॉइंट TeleClaw के इंफ्रास्ट्रक्चर द्वारा प्रबंधित प्रमाणपत्रों के साथ HTTPS पर परोसे जाते हैं। कोई Let’s Encrypt सेटअप नहीं, कोई Certbot क्रॉन जॉब नहीं।
• डिलीवरी निगरानी। TeleClaw प्रत्येक आने वाले अपडेट को ट्रैक करता है, डिलीवरी त्रुटियों को लॉग करता है, और उन्हें आपके डैशबोर्ड में प्रदर्शित करता है ताकि आप getWebhookInfo को मैन्युअल रूप से पोल किए बिना समस्याओं का निदान कर सकें।
• पुन: प्रयास दृश्यता। जब टेलीग्राम एक विफल अपडेट को फिर से प्रयास करता है, तो TeleClaw आपको दिखाता है कि यह क्यों विफल हुआ और कितने पुन: प्रयास हुए।
• डिफ़ॉल्ट रूप से स्केलेबल। TeleClaw का एज इंफ्रास्ट्रक्चर आपके हिस्से पर किसी भी कॉन्फ़िगरेशन के बिना ट्रैफिक स्पाइक्स को संभालने के लिए स्केल करता है।

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

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

यदि आपके पास पहले से ही एक पोलिंग बॉट है और आप माइग्रेट करना चाहते हैं:

1. अपने कोड से पोलिंग लूप हटाएँ। यदि आप getUpdates का उपयोग करते हैं, तो इसे कॉल करना बंद कर दें।
2. अपना HTTPS एंडपॉइंट प्रदान करें और इसके पीछे अपनी मौजूदा हैंडलर तर्क को तैनात करें।
3. अपने नए URL के साथ setWebhook को कॉल करें। यह स्वचालित रूप से किसी भी सक्रिय पोलिंग को रद्द कर देता है।
4. यदि आप संचित बैकलॉग को स्टार्टअप पर पुराने संदेशों को संसाधित करने के बजाय छोड़ना चाहते हैं तो drop_pending_updates: true सेट करें।
5. getWebhookInfo के साथ सत्यापित करें और अपडेट आने की पुष्टि करने के लिए एक परीक्षण संदेश भेजें।

माइग्रेशन आमतौर पर प्रतिवर्ती होता है: deleteWebhook को कॉल करने से वेबहुक कॉन्फ़िगरेशन हट जाता है और आपको getUpdates के माध्यम से पोलिंग फिर से शुरू करने की अनुमति मिलती है।

सारांश

टेलीग्राम बॉट वेबहुक्स अपडेट प्राप्त करने का प्रोडक्शन-ग्रेड तरीका है। वे पोलिंग ओवरहेड को समाप्त करते हैं, विलंबता को कम करते हैं, और साफ-सुथरा स्केल करते हैं। सेटअप के लिए एक HTTPS एंडपॉइंट, एक वैध प्रमाणपत्र, और setWebhook को कॉल करने की आवश्यकता होती है — यह सब आधुनिक टूलिंग के साथ प्रबंधनीय है। सबसे आम कमियाँ (धीमी प्रतिक्रिया समय, समाप्त प्रमाणपत्र, लापता फ़ायरवॉल नियम) के अच्छी तरह से समझे गए समाधान हैं, एक बार जब आप जानते हैं कि कहाँ देखना है।

उन टीमों के लिए जो इंफ्रास्ट्रक्चर के काम को पूरी तरह से छोड़ना चाहते हैं, TeleClaw वेबहुक पंजीकरण, TLS, निगरानी और स्केलिंग को स्वचालित रूप से संभालता है — जिससे आप DevOps विशेषज्ञ बने बिना एक विश्वसनीय, तेज़ टेलीग्राम बॉट शिप कर सकते हैं।

बिना वेबहुक्स को स्वयं प्रबंधित किए एक प्रोडक्शन टेलीग्राम बॉट तैनात करने के लिए तैयार हैं?

आज ही TeleClaw के साथ निर्माण शुरू करें।

TeleClaw.bot पर जाएँ या टेलीग्राम पर सीधे @claw के साथ इंटरैक्ट करें