लोकलहोस्ट पर टेलीग्राम बॉट वेबहुक का परीक्षण करने के लिए, सार्वजनिक HTTPS सुरंग के साथ अपने स्थानीय सर्वर को उजागर करें, उस URL के साथ setWebhook पर कॉल करें, और हर अनुरोध पर टेलीग्राम के गुप्त-टोकन हेडर को मान्य करें। यह आपको वास्तविक संदेश, कॉलबैक-क्वेरी और सदस्यता अपडेट देता है। प्रत्येक कोड परिवर्तन के बाद तैनाती के बिना। पूरा लूप है: बॉट हैंडलर चलाएँ, npx portpreview 3000 प्रारंभ करें, परिणामी URL पंजीकृत करें, अपने बॉट को एक संदेश भेजें, और स्थानीय रूप से अनुरोध का निरीक्षण करें।
टेलीग्राम सीधे लोकलहोस्ट पर अपडेट क्यों नहीं भेज सकता
टेलीग्राम का बॉट एपीआई टेलीग्राम इंफ्रास्ट्रक्चर से वेबहुक अपडेट को इंटरनेट-पहुंच योग्य यूआरएल पर भेजता है। localhost, 127.0.0.1, और निजी LAN पते उस बुनियादी ढांचे से निष्क्रिय नहीं हैं। एक localhost सुरंग सार्वजनिक पते पर HTTPS को समाप्त करता है और अपरिवर्तित HTTP अनुरोध को आपके स्थानीय पोर्ट पर अग्रेषित करता है।
टेलीग्राम बॉट दो परस्पर अनन्य तरीकों से अपडेट प्राप्त कर सकते हैं: getUpdates, या वेबहुक के माध्यम से लंबी पोलिंग। आधिकारिक setWebhook संदर्भ बताता है कि getUpdates अनुपलब्ध है जबकि एक आउटगोइंग वेबहुक कॉन्फ़िगर किया गया है। यदि कोई मतदान प्रक्रिया अभी भी चल रही है, तो वेबहुक प्रवाह का आकलन करने से पहले उसे रोक दें।
एक स्थानीय वेबहुक एंडपॉइंट बनाएं
यह एक्सप्रेस उदाहरण हैंडलर को जानबूझकर छोटा रखता है। यह अपडेट को छूने से पहले साझा किए गए रहस्य की जांच करता है, तुरंत स्वीकार करता है, और प्रतिक्रिया पथ से बाहर काम करता है।
import express from 'express';
import crypto from 'node:crypto';
const app = express();
app.use(express.json({ limit: '1mb' }));
function sameSecret(received = '', expected = '') {
const a = Buffer.from(received);
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/webhooks/telegram', (req, res) => {
const received = req.get('x-telegram-bot-api-secret-token') || '';
if (!sameSecret(received, process.env.TELEGRAM_WEBHOOK_SECRET)) {
return res.sendStatus(401);
}
const update = req.body;
res.sendStatus(200);
queueMicrotask(() => handleUpdate(update));
});
app.listen(3000, () => console.log('Listening on http://localhost:3000'));टेलीग्राम एक JSON-क्रमबद्ध Update भेजता है। HMAC-आधारित प्रदाताओं के विपरीत, टेलीग्राम का secret_token फीचर बॉडी पर हस्ताक्षर नहीं करता है। यह आपके चुने हुए मान को X-Telegram-Bot-Api-Secret-Token में रखता है। टोकन साबित करता है कि प्रेषक को वेबहुक पंजीकृत होने पर उपयोग किए गए मूल्य का पता है, लेकिन यह पेलोड डाइजेस्ट प्रदान नहीं करता है। टीएलएस ट्रांज़िट में अनुरोध की सुरक्षा करता है।
HTTPS के साथ समापन बिंदु को उजागर करें
- ऐप प्रारंभ करें और पुष्टि करें कि
curl -i http://localhost:3000/webhooks/telegramसर्वर तक पहुंचता है, भले ही GET 404 लौटाता हो। - दूसरा टर्मिनल खोलें और
npx portpreview 3000चलाएं। - सार्वजनिक HTTPS मूल की प्रतिलिपि बनाएँ और
/webhooks/telegramजोड़ें। - टेलीग्राम द्वारा अपडेट वितरित करते समय टनल प्रक्रिया चालू रखें।
बॉट एपीआई HTTPS वेबहुक यूआरएल स्वीकार करता है। टेलीग्राम दस्तावेज़ पोर्ट 443, 80, 88, और 8443 पर वेबहुक समर्थन; एक प्रबंधित सुरंग का सार्वजनिक समापन बिंदु आम तौर पर 443 का उपयोग करता है, तब भी जब अग्रेषित स्थानीय प्रक्रिया 3000 पर सुनती है।
टेलीग्राम वेबहुक को सुरक्षित रूप से पंजीकृत करें
एक यादृच्छिक रहस्य बनाएं जिसमें केवल अक्षर, अंक, अंडरस्कोर या हाइफ़न हों। टेलीग्राम 1-256 अक्षरों की अनुमति देता है। इस मान के रूप में बॉट टोकन का पुन: उपयोग न करें।
export TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"
curl -sS -X POST \
"https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
-d "url=https://YOUR-TUNNEL.portpreview.dev/webhooks/telegram" \
-d "secret_token=${TELEGRAM_WEBHOOK_SECRET}" \
-d 'allowed_updates=["message","callback_query"]' \
-d "drop_pending_updates=true"allowed_updates शोर को कम करता है और केवल उन अद्यतन प्रकारों को सूचीबद्ध करना चाहिए जिन्हें बॉट संभालता है। drop_pending_updates=true एक नया स्थानीय सत्र शुरू करते समय उपयोगी है, लेकिन यह कतारबद्ध अपडेट को स्थायी रूप से हटा देता है, इसलिए जब वे घटनाएँ मायने रखती हैं तो इसे छोड़ दें। टेलीग्राम का अपडेट दस्तावेज़ message, callback_query, और my_chat_member.
डिबगिंग कोड से पहले पंजीकरण की पुष्टि करें
कॉन्फ़िगरेशन विफलताओं को हैंडलर विफलताओं से अलग करने के लिए getWebhookInfo का उपयोग करें:
curl -sS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo"चेक url, pending_update_count, last_error_message, और last_error_date। खाली यूआरएल का मतलब है कि पंजीकरण नहीं रुका। बढ़ती लंबित संख्या का आम तौर पर मतलब है कि टेलीग्राम कनेक्ट नहीं हो सकता है या आपका एंडपॉइंट गैर-2xx स्थिति लौटाता है। पंजीकरण के बाद बॉट को सीधा संदेश भेजें; केवल चैट खोलने से जरूरी नहीं कि कोई अपडेट बन जाए।
पुनः प्रयास किए बिना अपडेट संभालें
धीमे काम से पहले स्वीकार करें
अनुरोध प्रमाणित और स्थायी रूप से स्वीकार होते ही 2xx प्रतिक्रिया लौटाएं। डेटाबेस निर्यात, एआई कॉल और तृतीय-पक्ष एपीआई को अतुल्यकालिक रूप से चलना चाहिए। टेलीग्राम गैर-2xx प्रतिक्रियाओं के बाद असफल अनुरोधों को पुनः प्रयास करता है, इसलिए धीमी गति से समकालिक कार्य डुप्लिकेट बना सकता है।
update_id
के साथ डुप्लिकेट करेंहर अपडेट में update_id होता है। संसाधित आईडी को समाप्ति विंडो के साथ संग्रहीत करें या एक अद्वितीय डेटाबेस कुंजी लागू करें। पुनः प्रयास के लिए दूसरी भुगतान रसीद नहीं भेजनी चाहिए, डुप्लिकेट टिकट नहीं बनाना चाहिए, या एक ही कॉलबैक को दो बार निष्पादित नहीं करना चाहिए।
प्रत्येक अद्यतन प्रकार को स्पष्ट रूप से मॉडल करें
हर अपडेट में message.text नहीं होता। कॉलबैक बटन callback_query के अंतर्गत आते हैं; चैनल पोस्ट और सदस्यता परिवर्तन में अन्य फ़ील्ड हैं। वर्तमान शीर्ष-स्तरीय फ़ील्ड पर शाखा लगाएं और अज्ञात प्रकारों को फेंकने के बजाय वैध नो-ऑप्स के रूप में मानें।
स्थानीय टेलीग्राम बॉट परीक्षण के लिए सुरक्षा नियम
- पहले गुप्त हेडर को मान्य करें। संवेदनशील फ़ील्ड को लॉग करने या पार्स करने से पहले गुम या गलत मानों को अस्वीकार करें।
- टोकन को यूआरएल और लॉग से दूर रखें। पंजीकरण कमांड में बॉट एपीआई टोकन एक क्रेडेंशियल है। साझा सिस्टम पर शेल इतिहास से बचें और BotFather के माध्यम से एक उजागर टोकन को घुमाएँ।
- अकल्पनीय मार्ग और रहस्य का उपयोग करें। मार्ग गहराई में रक्षा है; गुप्त हेडर वास्तविक एप्लिकेशन जांच है।
- कैप्चर किए गए डेटा को सीमित करें। संदेशों में नाम, उपयोगकर्ता नाम, फ़ोन नंबर, फ़ाइलें और निजी वार्तालाप पाठ शामिल हो सकते हैं। लॉग को संशोधित करें और समाप्त होने पर स्थानीय कैप्चर हटा दें।
- विकास में प्रमाणीकरण को कभी भी अक्षम न करें। एक सार्वजनिक सुरंग सार्वजनिक है। स्थानीय कोड को उत्पादन के समान ही जांच करनी चाहिए।
एक्सेस-कंट्रोल और डेटा-रिटेंशन प्रथाओं के लिए व्यापक localhost सुरंग सुरक्षा गाइड देखें।
सामान्य टेलीग्राम वेबहुक विफलताओं का निवारण करें
टेलीग्राम एक प्रमाणपत्र या कनेक्शन त्रुटि की रिपोर्ट करता है
सुरंग के HTTPS URL का उपयोग करें, न कि उसके स्थानीय HTTP लक्ष्य का। पुष्टि करें कि सुरंग सक्रिय है और URL नहीं बदला है। यदि आप इसके बजाय अपना स्व-हस्ताक्षरित प्रमाणपत्र प्रदान करते हैं, तो टेलीग्राम को सार्वजनिक प्रमाणपत्र को फ़ाइल के रूप में अपलोड करने की आवश्यकता होती है; एक प्रबंधित टीएलएस समापन बिंदु उस सेटअप से बचता है।
एंडपॉइंट रिटर्न 401
प्रक्रिया द्वारा उपयोग किए गए पर्यावरण चर के साथ setWebhook को दिए गए रहस्य की तुलना करें। हेडर नाम केस-असंवेदनशील होते हैं, लेकिन प्रॉक्सी या मिडलवेयर कस्टम हेडर को हटा सकते हैं। गुप्त मान को प्रिंट किए बिना आने वाले हेडर का निरीक्षण करें।
कोई अनुरोध नहीं आया
Run getWebhookInfo, सत्यापित करें कि पंजीकृत पथ बिल्कुल आपके मार्ग से मेल खाता है, और सुनिश्चित करें कि कोई फ़ायरवॉल सुरंग के स्थानीय कनेक्शन को अवरुद्ध न करे। यदि आपने हाल ही में मतदान का उपयोग किया है, तो पुष्टि करें कि वेबहुक यूआरएल अब भर गया है। बॉट को संदेश भेजकर वास्तविक अपडेट ट्रिगर करें।
अपडेट बार-बार आते हैं
लॉग स्थिति और प्रतिक्रिया समय। अनुरोध प्राप्त करने के बाद अपवाद इच्छित 200 को 500 में बदल सकते हैं। 200 को तुरंत लौटाएं, प्रसंस्करण को निष्क्रिय बनाएं, और डिबगिंग के दौरान प्रदाता के पुनः प्रयास की प्रतीक्षा करने के बजाय नियंत्रित वेबहुक रीप्ले का उपयोग करें।
कॉलबैक क्वेरी और फ़ाइलों का परीक्षण करें, न केवल टेक्स्ट
एक उपयोगी बॉट परीक्षण मैट्रिक्स message.text से अधिक को कवर करता है। कैप्शन के साथ एक फोटो भेजें, एक संपर्क साझा करें, एक संदेश संपादित करें, और एक इनलाइन-कीबोर्ड बटन दबाएँ। कॉलबैक प्रश्नों के लिए, तुरंत answerCallbackQuery पर कॉल करें ताकि क्लाइंट अपना प्रगति संकेतक दिखाना बंद कर दे, फिर अलग से धीमा काम करें। फ़ाइल अद्यतन में पहचानकर्ता होते हैं; बाइट्स डाउनलोड करना एक दूसरा बॉट एपीआई ऑपरेशन है और इससे वेबहुक प्रतिक्रिया में देरी नहीं होनी चाहिए।
यूनिट परीक्षणों के लिए सैनिटाइज्ड अपडेट से बने फिक्स्चर रखें, लेकिन प्रत्येक समर्थित प्रकार के कम से कम एक परीक्षण के लिए पूर्ण परिवहन पथ को सुरक्षित रखें। एक फिक्स्चर साबित करता है कि आपका डिस्पैचर पेलोड को समझता है; एक वास्तविक सुरंगयुक्त डिलीवरी पंजीकरण, टीएलएस, हेडर, बॉडी पार्सिंग और पावती व्यवहार को भी साबित करती है। नई allowed_updates प्रविष्टि जोड़ते समय, setWebhook को दोबारा कॉल करें और सत्यापित करें कि getWebhookInfo इच्छित कॉन्फ़िगरेशन को दर्शाता है।
स्थानीय सत्र के बाद वेबहुक हटाएं
curl -sS -X POST \
"https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/deleteWebhook" \
-d "drop_pending_updates=false"वेबहुक को हटाने से आप getUpdates पर वापस लौट सकते हैं। यदि अगले सत्र में टनल यूआरएल बदलता है, तो setWebhook पर फिर से कॉल करें। अतिरिक्त निदान के लिए, सामान्य स्थानीय वेबहुक डिबगिंग वर्कफ़्लो.