Telegram टूलकिट

Telegram टूलकिट एजेंट्स और वर्कफ़्लो को Telegram bots के साथ इंटरैक्ट करने देता है। यह संदेश भेजने और संपादित करने, मीडिया भेजने, चैट सदस्यों को प्रबंधित करने, आमंत्रण लिंक बनाने और इनकमिंग संदेशों से वर्कफ़्लो ट्रिगर करने के लिए webhooks रजिस्टर करने का समर्थन करता है।

Telegram bots और उनके क्रेडेंशियल्स @BotFather नामक Telegram bot के माध्यम से प्रबंधित होते हैं — कोई वेब डेवलपर कंसोल नहीं है।

पूर्वावश्यकताएं

आवश्यकता	विवरण
Telegram खाता	@BotFather के साथ इंटरैक्ट करने के लिए आवश्यक

चरण 1 — Telegram Bot बनाएं

1. @BotFather खोलें

   Telegram खोलें और @BotFather के साथ बातचीत शुरू करें।

2. नया bot बनाएं

   कमांड /newboat भेजें और प्रॉम्प्ट का पालन करें:

   प्रॉम्प्ट	विवरण
   Bot का नाम	एक मानव-पठनीय प्रदर्शन नाम (जैसे My App)
   यूज़रनेम	अद्वितीय होना चाहिए और bot पर समाप्त होना चाहिए (जैसे myapp_bot)

3. अपना bot टोकन कॉपी करें

   BotFather एक सफलता संदेश के साथ उत्तर देगा जिसमें आपका bot टोकन होगा — यह कुछ इस तरह दिखता है 123456789:ABCdefGHijkLmNoPQRsTUVwxyz। इसे कॉपी करें और सुरक्षित रूप से सहेजें।

सुझाव

BotFather में /setuserpic कमांड का उपयोग करके अपने एप्लिकेशन लोगो से मेल खाता प्रोफ़ाइल चित्र सेट करें। एक पहचानने योग्य चित्र आपके bot को उपयोगकर्ताओं के लिए पेशेवर और भरोसेमंद बनाता है।

चरण 2 — EKB में टोकन जोड़ें

Workflow Builder

1. वर्कफ़्लो में, एक Telegram टूलकिट चरण जोड़ें।
2. Select a Connection → Create a Connection पर क्लिक करें।
3. Connection Name दर्ज करें और अपना bot टोकन पेस्ट करें।
4. Save पर क्लिक करें।

Agent Builder

1. Agent Builder में अपना एजेंट खोलें।
2. बाईं साइडबार में Toolkits टैब पर जाएं।
3. Telegram खोजें और Add to Agent पर क्लिक करें।
4. Telegram Bot Token के नीचे अपना bot टोकन पेस्ट करें।
5. Save पर क्लिक करें।

अपने टोकन का प्रबंधन

खतरा

आपका bot टोकन आपके bot की मास्टर कुंजी है। इसे साझा न करें, सार्वजनिक रिपॉज़िटरी में कमिट न करें, या क्लाइंट-साइड कोड में एक्सपोज़ न करें।

यदि आपका टोकन गलती से लीक हो जाता है, तो इसे तुरंत रद्द करें:

1. @BotFather को संदेश भेजें
2. /mybots भेजें
3. अपना bot चुनें
4. API Token → Revoke current token टैप करें

एक नया टोकन जनरेट होगा। EKB में नए मान के साथ कनेक्शन अपडेट करें।

उपलब्ध टूल्स

टूल	विवरण
नया संदेश (ट्रिगर)	जब आपके bot को कोई संदेश भेजा जाता है तो वर्कफ़्लो शुरू करें
टेक्स्ट संदेश भेजें	अपने bot से किसी भी चैट में टेक्स्ट संदेश भेजें
मीडिया भेजें	फ़ोटो, वीडियो, स्टिकर या एनिमेटेड GIF भेजें
संदेश टेक्स्ट संपादित करें	पहले भेजे गए संदेश का टेक्स्ट अपडेट करें
संदेश हटाएं	चैट से संदेश हटाएं
चैट जानकारी प्राप्त करें	चैट का मेटाडेटा प्राप्त करें
चैट सदस्य प्राप्त करें	चैट में उपयोगकर्ता की सदस्यता स्थिति देखें
आमंत्रण लिंक बनाएं	किसी समूह या चैनल के लिए आमंत्रण लिंक जनरेट करें
Webhook रजिस्टर करें	Telegram को bot संदेशों को अपने वर्कफ़्लो में फ़ॉरवर्ड करने के लिए कहें
Webhook हटाएं	Webhook हटाएं और संदेश वितरण बंद करें

ट्रिगर — नया संदेश

जब कोई व्यक्ति आपके Telegram bot को संदेश भेजता है तो स्वचालित रूप से वर्कफ़्लो शुरू करता है।

सेटअप:

1. ट्रिगर जोड़ें

   अपने वर्कफ़्लो के पहले चरण के रूप में नया संदेश ट्रिगर जोड़ें। ट्रिगर कॉन्फ़िगरेशन पैनल से /tool-webhook/{workflow-id} URL कॉपी करें।

2. Webhook रजिस्टर करें

   Telegram को उस URL पर संदेश वितरित करने के लिए कहने के लिए Webhook रजिस्टर करें चरण का उपयोग करें। इसे एक बार चलाएं — नीचे Webhook रजिस्टर करें देखें।

3. परीक्षण करें

   अपने bot को एक परीक्षण संदेश भेजें। वर्कफ़्लो फ़ायर होता है और सभी संदेश डेटा वेरिएबल्स के रूप में उपलब्ध होता है।

उपलब्ध ट्रिगर वेरिएबल्स:

वेरिएबल	विवरण
{{ trigger.body.message.text }}	उपयोगकर्ता द्वारा भेजा गया संदेश टेक्स्ट
{{ trigger.body.message.chat.id }}	चैट ID — सभी भेजने वाले चरणों में Chat ID के रूप में इसका उपयोग करें
{{ trigger.body.message.from.id }}	भेजने वाले की Telegram उपयोगकर्ता ID
{{ trigger.body.message.from.first_name }}	भेजने वाले का पहला नाम
{{ trigger.body.message.from.username }}	भेजने वाले का यूज़रनेम (खाली हो सकता है)
{{ trigger.body.message.message_id }}	इनकमिंग संदेश की ID
{{ trigger.body.update_id }}	Telegram से अद्वितीय अपडेट ID

मैसेजिंग कार्य

टेक्स्ट संदेश भेजें

अपने bot से किसी भी चैट में टेक्स्ट संदेश भेजता है।

मुख्य इनपुट:

इनपुट	विवरण
Chat ID	भेजने के लिए चैट। वर्कफ़्लो को ट्रिगर करने वाले व्यक्ति के लिए, {{ trigger.body.message.chat.id }} का उपयोग करें। स्थिर समूह या चैनल के लिए, इसकी संख्यात्मक ID पेस्ट करें।
Message	भेजने के लिए टेक्स्ट। स्थिर टेक्स्ट और वेरिएबल्स को मिलाएं, जैसे Hello {{ trigger.body.message.from.first_name }}, your request was received.
Format	प्लेन टेक्स्ट के लिए खाली छोड़ें। <b>bold</b> / <i>italic</i> के लिए HTML सेट करें। Markdown के लिए MarkdownV2 सेट करें (विशेष वर्ण स्वचालित रूप से एस्केप होते हैं)।
Disable Web Page Preview	लिंक पूर्वावलोकन दबाने के लिए true सेट करें
Message Thread ID	वैकल्पिक — केवल Forum supergroups के लिए प्रासंगिक
Reply Markup	वैकल्पिक — इनलाइन कीबोर्ड या कस्टम रिप्लाई कीबोर्ड के लिए JSON ऑब्जेक्ट

डाउंस्ट्रीम चरणों में आउटपुट का संदर्भ:

• Message ID (बाद में Edit या Delete के लिए आवश्यक): {{ step.output.message_id }}
• Chat ID: {{ step.output.chat_id }}

मीडिया भेजें

किसी चैट में फ़ोटो, वीडियो, स्टिकर या एनिमेटेड GIF भेजता है।

मुख्य इनपुट:

इनपुट	विवरण
Chat ID	भेजने के लिए चैट
Media Type	बिल्कुल इनमें से एक होना चाहिए: photo, video, sticker, animation
Media URL	फ़ाइल का सार्वजनिक रूप से सुलभ HTTPS URL — Telegram इसे सीधे फ़ेच करता है
Media ID	वैकल्पिक रूप से, पहले अपलोड की गई फ़ाइल से Telegram file_id। Media URL या Media ID में से कोई एक दें, दोनों नहीं।
Caption	वैकल्पिक टेक्स्ट जो मीडिया के नीचे दिखाया जाता है। Format के माध्यम से HTML/MarkdownV2 का समर्थन करता है।
Format	कैप्शन के लिए पार्स मोड
Message Thread ID	वैकल्पिक — forum supergroup विषयों के लिए

नोट

यदि Media URL या Media ID में से कोई नहीं दिया जाता है, तो चरण त्रुटि लौटाता है। URL सार्वजनिक रूप से पहुँच योग्य होना चाहिए — स्थानीय या निजी URLs काम नहीं करेंगे।

संदेश टेक्स्ट संपादित करें

आपके bot द्वारा पहले भेजे गए संदेश का टेक्स्ट अपडेट करता है।

मुख्य इनपुट:

इनपुट	विवरण
Chat ID	मूल संदेश वाला चैट
Message ID	टेक्स्ट संदेश भेजें आउटपुट से message_id — {{ step.output.message_id }}
Text	नया संदेश सामग्री
Format	नए टेक्स्ट के लिए पार्स मोड (खाली = प्लेन टेक्स्ट, HTML, या MarkdownV2)

उदाहरण उपयोग का मामला: पहले "Processing your request…" भेजें। वर्कफ़्लो तर्क चलाएं। फिर अंतिम परिणाम के साथ उस संदेश को संपादित करें — उपयोगकर्ता को दो के बजाय एक संदेश दिखाई देता है।

संदेश हटाएं

चैट से संदेश हटाता है।

मुख्य इनपुट:

इनपुट	विवरण
Chat ID	संदेश वाला चैट
Message ID	हटाने के लिए संदेश की message_id

नोट

बॉट्स केवल अपने स्वयं के संदेश हटा सकते हैं जब तक कि बॉट चैट में एडमिन न हो। Telegram एक समय सीमा भी लागू करता है — 48 घंटे से पुराने संदेश आमतौर पर बॉट्स द्वारा नहीं हटाए जा सकते।

चैट और सदस्य कार्य

चैट जानकारी प्राप्त करें

चैट का मेटाडेटा प्राप्त करता है।

मुख्य इनपुट:

इनपुट	विवरण
Chat ID	देखने के लिए चैट

डाउंस्ट्रीम चरणों में मानों का संदर्भ:

• चैट शीर्षक: {{ step.output.title }}
• विवरण: {{ step.output.description }}
• आमंत्रण लिंक: {{ step.output.invite_link }}

चैट सदस्य प्राप्त करें

चैट में एक विशिष्ट उपयोगकर्ता को खोजता है और उनकी सदस्यता स्थिति और भूमिका लौटाता है।

मुख्य इनपुट:

इनपुट	विवरण
Chat ID	खोजने के लिए चैट
User ID	खोजने के लिए Telegram उपयोगकर्ता ID। वर्कफ़्लो को ट्रिगर करने वाले व्यक्ति के लिए, {{ trigger.body.message.from.id }} का उपयोग करें।

डाउंस्ट्रीम चरणों में मानों का संदर्भ:

• स्थिति: {{ step.output.status }}
• यूज़रनेम: {{ step.output.username }}

संभव स्थिति मान: creator, administrator, member, restricted, left, kicked

उदाहरण उपयोग का मामला: {{ step.output.status }} जांचें — यदि यह left या kicked के बराबर है, तो संदेश भेजने से छोड़ें और त्रुटि संभालें।

आमंत्रण लिंक बनाएं

किसी समूह या चैनल के लिए एक नया आमंत्रण लिंक जनरेट करता है।

नोट

बॉट लक्ष्य चैट में "Invite Users" अनुमति के साथ एक एडमिनिस्ट्रेटर होना चाहिए।

मुख्य इनपुट:

इनपुट	विवरण
Chat ID	समूह या चैनल
Name	वैकल्पिक लिंक लेबल (अधिकतम 32 वर्ण), Telegram एडमिन पैनल में दिखाई देता है
Expire Date	वैकल्पिक। एक ISO-8601 स्ट्रिंग जब लिंक समाप्त होता है, जैसे 2026-12-31T23:59:59Z। आंतरिक रूप से unix timestamp में बदला जाता है।
Member Limit	वैकल्पिक। इस लिंक के माध्यम से शामिल होने वाले लोगों की अधिकतम संख्या (1-99,999)

डाउंस्ट्रीम चरणों में लिंक का संदर्भ:

• आमंत्रण URL: {{ step.output.invite_link }}

नोट

आउटपुट में expire_date एक unix timestamp (पूर्णांक सेकंड) है, ISO प्रारूप नहीं। creates_join_request true होगा यदि चैट नए सदस्यों के लिए एडमिन अनुमोदन की आवश्यकता रखता है।

Webhook सेटअप कार्य

ये दो चरण नए संदेश ट्रिगर को आपके bot से जोड़ते हैं। प्रत्येक वर्कफ़्लो के लिए इन्हें एक बार चलाएं।

Webhook रजिस्टर करें

Telegram को आपके bot से अपने वर्कफ़्लो URL पर संदेश फ़ॉरवर्ड करना शुरू करने के लिए कहता है।

मुख्य इनपुट:

इनपुट	विवरण
URL	नया संदेश ट्रिगर पैनल से /tool-webhook/{workflow-id} URL
Allowed Updates	केवल नियमित संदेश प्राप्त करने के लिए ["message"] सेट करें (अनुशंसित)। डिफ़ॉल्ट उपयोग करने के लिए खाली छोड़ें।
Secret Token	वैकल्पिक लेकिन अनुशंसित। कोई भी यादृच्छिक स्ट्रिंग (जैसे my-secret-abc123)। Telegram इसे प्रत्येक webhook अनुरोध हेडर में शामिल करता है ताकि आप सत्यापित कर सकें कि अनुरोध प्रामाणिक हैं।
Drop Pending Updates	Webhook रजिस्टर होने से पहले आए संदेशों को अनदेखा करने के लिए true सेट करें

1. ट्रिगर URL कॉपी करें

   नए संदेश ट्रिगर के साथ वर्कफ़्लो बनाएं। ट्रिगर पैनल से /tool-webhook/{workflow-id} URL कॉपी करें।

2. Webhook रजिस्टर करें जोड़ें

   एक अलग एक-बार वर्कफ़्लो या मैनुअल टेस्ट रन में, Webhook रजिस्टर करें चरण जोड़ें और ऊपर दिए गए इनपुट भरें।

3. एक बार चलाएं

   चरण चलाएं। फिर अपने bot को संदेश भेजें — आपका मुख्य वर्कफ़्लो अब फ़ायर होना चाहिए।

वैकल्पिक रूप से, त्वरित एक-बार सेटअप के लिए curl के माध्यम से रजिस्टर करें:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/tool-webhook/<YOUR_WORKFLOW_ID>",
    "allowed_updates": ["message"],
    "secret_token": "my-secret-abc123"
  }'

एक सफल प्रतिक्रिया:

{ "ok": true, "result": true, "description": "Webhook was set" }

नोट

एक Telegram bot के पास एक समय में केवल एक सक्रिय webhook हो सकता है। एक नया URL रजिस्टर करने से कोई भी पिछला URL बदल जाता है।

Webhook हटाएं

Webhook हटाता है और Telegram को आपके वर्कफ़्लो में संदेश वितरित करने से रोकता है।

मुख्य इनपुट:

इनपुट	विवरण
Drop Pending Updates	Webhook सक्रिय होने के दौरान कतार में लगे सभी संदेशों को त्यागने के लिए true सेट करें

नोट

जब आप वर्कफ़्लो रिटायर या आर्काइव करें तो webhook हटा दें। यदि आप webhook को रजिस्टर्ड छोड़ देते हैं लेकिन वर्कफ़्लो निष्क्रिय है, तो Telegram अनुत्तरित अनुरोध भेजता रहेगा।

समस्या निवारण

लक्षण	संभावित कारण	समाधान
वर्कफ़्लो नए संदेशों पर फ़ायर नहीं होता	Webhook रजिस्टर्ड नहीं है या गलत URL पर इंगित कर रहा है	सही ट्रिगर URL के साथ Webhook रजिस्टर करें चलाएं
401 Unauthorized	Bot टोकन अमान्य है या रद्द कर दिया गया है	टोकन सत्यापित करें या @BotFather के माध्यम से नया जनरेट करें
मीडिया वितरित नहीं होता	URL सार्वजनिक रूप से सुलभ नहीं है	सार्वजनिक HTTPS URL का उपयोग करें — स्थानीय या निजी URLs काम नहीं करेंगे
संदेश हटा नहीं सकता	संदेश 48 घंटे से पुराना है, या बॉट एडमिन नहीं है	बॉट्स केवल हाल के संदेश हटा सकते हैं जब तक उनके पास एडमिन विशेषाधिकार न हों
आमंत्रण लिंक पर creates_join_request: true	चैट नए सदस्यों के लिए एडमिन अनुमोदन की आवश्यकता रखता है	यह अपेक्षित व्यवहार है — शामिल होने से पहले उपयोगकर्ताओं को अनुमोदित किया जाना चाहिए
पुराने संदेश वर्कफ़्लो को ट्रिगर कर रहे हैं	Webhook रजिस्ट्रेशन के दौरान लंबित अपडेट साफ़ नहीं हुए	Drop Pending Updates को true सेट करके पुनः रजिस्टर करें