نود Telegram در N8N

نود Telegram در N8N

نود Telegram در N8N یکی از کاربردی‌ترین نودها برای ساخت ربات‌های تلگرامی، ارسال اعلان، دریافت پیام، مدیریت فایل‌ها و اتصال ورکفلوهای اتوماسیون به تلگرام است. با این نود می‌توانید بدون کدنویسی پیچیده، یک بات تلگرام را به سیستم‌های مختلف مثل Google Sheets، CRM، دیتابیس، وب‌سرویس‌ها، سیستم پشتیبانی، هوش مصنوعی و ابزارهای مانیتورینگ متصل کنید.

این نود برای پروژه‌هایی مثل ارسال گزارش روزانه، هشدار خطا، دریافت سفارش، پاسخ خودکار، ثبت درخواست کاربران و ساخت پنل مدیریتی ساده در تلگرام بسیار مفید است.

معرفی نود در N8N

در N8N دو نوع نود اصلی برای کار با تلگرام وجود دارد:

• Telegram Trigger: برای شروع کردن ورکفلو زمانی که یک رویداد در تلگرام رخ می‌دهد؛ مثل دریافت پیام، کلیک روی دکمه، ارسال فایل یا ورود دستور توسط کاربر.
• Telegram: برای انجام عملیات روی تلگرام؛ مثل ارسال پیام، ارسال عکس، ارسال فایل، ویرایش پیام، پاسخ به Callback Query و دریافت اطلاعات فایل.

از نظر دسته‌بندی، Telegram Trigger در گروه Trigger قرار می‌گیرد، چون اجرای ورکفلو را آغاز می‌کند. نود Telegram در گروه Action / Integration قرار می‌گیرد، چون یک عملیات مشخص را روی سرویس خارجی Telegram انجام می‌دهد.

کاربرد اصلی این نود، اتصال ورکفلوهای خودکار به کاربران یا کانال‌ها و گروه‌های تلگرامی است. به کمک آن می‌توان تلگرام را به یک رابط کاربری ساده برای اتوماسیون تبدیل کرد؛ به‌طوری‌که کاربر در تلگرام پیام می‌فرستد و N8N در پشت صحنه اطلاعات را پردازش می‌کند، در دیتابیس ذخیره می‌کند یا پاسخ مناسب برمی‌گرداند.

موارد استفاده

ارسال اعلان‌های سیستمی

یکی از رایج‌ترین کاربردهای نود Telegram، ارسال هشدار و اعلان است. برای مثال، اگر یک سرور از دسترس خارج شود، پرداختی در سایت ثبت شود یا یک سفارش جدید ایجاد شود، N8N می‌تواند بلافاصله یک پیام تلگرام برای مدیر ارسال کند.

• ترکیب پیشنهادی: Cron + HTTP Request + IF + Telegram
• مثال عملی: هر ۵ دقیقه وضعیت API سایت بررسی شود و در صورت خطا، پیام هشدار به گروه فنی ارسال شود.

ساخت ربات پاسخ‌گوی خودکار

با ترکیب Telegram Trigger و نودهای شرطی، می‌توانید یک ربات ساده بسازید که بر اساس متن پیام کاربر پاسخ متفاوت بدهد.

• ترکیب پیشنهادی: Telegram Trigger + Switch + Set + Telegram
• مثال عملی: اگر کاربر عبارت /start را ارسال کند، پیام خوش‌آمدگویی دریافت کند. اگر عبارت قیمت را ارسال کند، لیست قیمت‌ها برای او ارسال شود.

ثبت اطلاعات کاربران در Google Sheets یا دیتابیس

می‌توانید پیام‌های دریافتی از تلگرام را در Google Sheets، Airtable، PostgreSQL، MySQL یا هر دیتابیس دیگری ذخیره کنید.

• ترکیب پیشنهادی: Telegram Trigger + Set + Google Sheets + Telegram
• مثال عملی: کاربر فرم متنی ارسال می‌کند، اطلاعات او در Google Sheets ثبت می‌شود و پیام تأیید دریافت می‌کند.

ارسال فایل، تصویر و گزارش

نود Telegram امکان ارسال فایل، عکس، ویدیو، فایل صوتی، موقعیت مکانی و سند را فراهم می‌کند. این قابلیت برای ارسال گزارش‌های روزانه، خروجی PDF، فایل CSV یا تصاویر تولیدشده توسط سیستم بسیار کاربردی است.

• ترکیب پیشنهادی: Schedule Trigger + Database + Spreadsheet File + Telegram
• مثال عملی: هر روز ساعت ۹ صبح فروش روز قبل از دیتابیس خوانده شود، به فایل اکسل تبدیل شود و در تلگرام برای مدیر ارسال شود.

اتصال تلگرام به هوش مصنوعی

یکی از سناریوهای محبوب، ساخت ربات تلگرام متصل به مدل‌های هوش مصنوعی است. پیام کاربر از Telegram Trigger دریافت می‌شود، سپس به OpenAI یا هر سرویس AI دیگر ارسال می‌شود و پاسخ تولیدشده با نود Telegram به کاربر برمی‌گردد.

• ترکیب پیشنهادی: Telegram Trigger + OpenAI + Telegram
• مثال عملی: ساخت رباتی که به سوالات کاربران پاسخ می‌دهد یا متن‌های طولانی را خلاصه می‌کند.

پارامترها و تنظیمات

پارامترهای نود Telegram بسته به نوع عملیات انتخاب‌شده تغییر می‌کنند. در ادامه مهم‌ترین تنظیمات عمومی و عملیاتی این نود توضیح داده شده‌اند.

تنظیمات احراز هویت

روش دریافت Bot Token از BotFather

• در تلگرام وارد ربات @BotFather شوید.
• دستور /newbot را ارسال کنید.
• نام نمایشی ربات را وارد کنید.
• Username ربات را وارد کنید؛ این نام باید به bot ختم شود، مثل mycompany_support_bot.
• BotFather یک توکن به شما می‌دهد.
• توکن را در بخش Credentials نود Telegram در N8N وارد کنید.

پارامترهای عمومی نود Telegram

عملیات Send Message

این عملیات برای ارسال پیام متنی به کاربر، گروه، کانال یا سوپرگروه استفاده می‌شود.

نمونه متن HTML در پیام تلگرام

اگر Parse Mode را روی HTML قرار دهید، می‌توانید از تگ‌های پشتیبانی‌شده تلگرام مثل b، i، code و a استفاده کنید.

<b>سفارش جدید</b>شماره سفارش: <code>1024</code>مبلغ: 850,000 تومان<a href="https://example.com/orders/1024">مشاهده سفارش</a>

عملیات Send Photo

برای ارسال تصویر از URL یا فایل باینری استفاده می‌شود.

عملیات Send Document

این عملیات برای ارسال فایل‌هایی مثل PDF، Excel، CSV، ZIP و سایر اسناد استفاده می‌شود.

عملیات Send Video، Send Audio و Send Voice

برای ارسال ویدیو، فایل صوتی یا پیام صوتی استفاده می‌شود. منبع فایل می‌تواند URL یا داده باینری تولیدشده در نودهای قبلی باشد.

عملیات Send Location

برای ارسال موقعیت جغرافیایی به کاربر یا گروه استفاده می‌شود.

عملیات Edit Message Text

برای ویرایش متن پیام‌هایی که قبلاً توسط همان بات ارسال شده‌اند استفاده می‌شود. این قابلیت برای ساخت منوهای تعاملی و تغییر وضعیت پیام بسیار کاربردی است.

عملیات Answer Callback Query

وقتی کاربر روی یک دکمه Inline Keyboard کلیک می‌کند، تلگرام یک Callback Query ارسال می‌کند. برای پاسخ به این رویداد و حذف حالت Loading روی دکمه، از Answer Callback Query استفاده می‌شود.

عملیات Get File

برای دریافت اطلاعات فایل ارسال‌شده توسط کاربر استفاده می‌شود. معمولاً ابتدا از Telegram Trigger شناسه فایل دریافت می‌شود، سپس با Get File اطلاعات مسیر فایل گرفته می‌شود و در مرحله بعد می‌توان فایل را دانلود یا پردازش کرد.

تنظیمات مهم Telegram Trigger

Telegram Trigger برای دریافت رویدادهای تلگرام و شروع ورکفلو استفاده می‌شود. این نود معمولاً با Webhook کار می‌کند و وقتی رویدادی از سمت تلگرام دریافت شود، ورکفلو اجرا می‌شود.

نکات مهم هنگام پیکربندی

• برای ارسال پیام به کاربر، کاربر باید ابتدا به ربات پیام داده باشد؛ بات نمی‌تواند به‌صورت مستقیم به کاربری که هیچ تعاملی با ربات نداشته پیام بدهد.
• برای ارسال پیام به گروه، باید ربات را به گروه اضافه کنید.
• برای ارسال پیام به کانال، ربات باید در کانال ادمین باشد.
• Chat ID گروه‌ها و سوپرگروه‌ها معمولاً عددی منفی است و ممکن است با -100 شروع شود.
• اگر از Parse Mode برابر HTML استفاده می‌کنید، فقط تگ‌های مجاز تلگرام قابل استفاده هستند و HTML کامل پشتیبانی نمی‌شود.
• در MarkdownV2 بسیاری از کاراکترها باید Escape شوند؛ برای کاربران مبتدی، HTML معمولاً ساده‌تر است.
• برای استفاده از Telegram Trigger در محیط Self-hosted، آدرس Webhook باید از اینترنت قابل دسترسی و دارای HTTPS معتبر باشد.
• اگر قبلاً برای بات Webhook دیگری تنظیم شده باشد، ممکن است Telegram Trigger درست کار نکند و باید Webhook قبلی پاک یا جایگزین شود.

ورودی‌ها و خروجی‌ها

ورودی نود Telegram

نود Telegram معمولاً داده‌های ورودی را از نودهای قبلی دریافت می‌کند. این داده‌ها می‌توانند شامل Chat ID، متن پیام، مسیر فایل، داده باینری، شناسه پیام یا اطلاعات کاربر باشند.

برای مثال، اگر Telegram Trigger قبل از نود Telegram قرار گرفته باشد، می‌توانید Chat ID کاربر را با Expression زیر استفاده کنید:

{{$json.message.chat.id}}

و متن پیام کاربر را با Expression زیر بخوانید:

{{$json.message.text}}

نمونه ورودی از Telegram Trigger

{  "update_id": 987654321,  "message": {    "message_id": 15,    "from": {      "id": 123456789,      "is_bot": false,      "first_name": "Ali",      "username": "ali_example",      "language_code": "fa"    },    "chat": {      "id": 123456789,      "first_name": "Ali",      "username": "ali_example",      "type": "private"    },    "date": 1710000000,    "text": "/start"  }}

خروجی نود Send Message

وقتی پیام با موفقیت ارسال شود، تلگرام اطلاعات پیام ایجادشده را برمی‌گرداند. این خروجی معمولاً شامل شناسه پیام، اطلاعات چت، تاریخ ارسال و متن پیام است.

{  "ok": true,  "result": {    "message_id": 101,    "from": {      "id": 555555555,      "is_bot": true,      "first_name": "My Bot",      "username": "my_company_bot"    },    "chat": {      "id": 123456789,      "first_name": "Ali",      "type": "private"    },    "date": 1710000050,    "text": "سلام، درخواست شما ثبت شد."  }}

خروجی Callback Query

اگر کاربر روی دکمه Inline کلیک کند، Telegram Trigger داده‌ای مشابه ساختار زیر برمی‌گرداند:

{  "update_id": 987654322,  "callback_query": {    "id": "1234567890123456789",    "from": {      "id": 123456789,      "first_name": "Ali",      "username": "ali_example"    },    "message": {      "message_id": 101,      "chat": {        "id": 123456789,        "type": "private"      },      "text": "لطفاً یکی از گزینه‌ها را انتخاب کنید."    },    "data": "confirm_order_1024"  }}

نمونه استفاده از داده‌های خروجی در نودهای بعدی

• استفاده از {{$json.message.chat.id}} برای پاسخ دادن به همان کاربر.
• استفاده از {{$json.message.text}} برای تشخیص دستور کاربر.
• استفاده از {{$json.callback_query.data}} برای تشخیص دکمه کلیک‌شده.
• استفاده از {{$json.message.document.file_id}} برای دریافت فایل ارسالی کاربر.
• استفاده از {{$json.message.message_id}} برای Reply یا ویرایش پیام.

نکات پیشرفته و ترفندها

ساخت منوی دکمه‌ای با Inline Keyboard

با استفاده از Reply Markup می‌توانید دکمه‌های تعاملی بسازید. این دکمه‌ها می‌توانند URL باز کنند یا Callback Data به N8N بفرستند.

{  "inline_keyboard": [    [      {        "text": "تایید",        "callback_data": "approve"      },      {        "text": "رد",        "callback_data": "reject"      }    ],    [      {        "text": "مشاهده سایت",        "url": "https://example.com"      }    ]  ]}

برای پردازش کلیک روی دکمه‌ها، در Telegram Trigger رویداد Callback Query را فعال کنید و سپس مقدار callback_query.data را با Switch بررسی کنید.

پاسخ دادن به همان پیام کاربر

برای اینکه پاسخ بات به‌صورت Reply زیر پیام کاربر نمایش داده شود، مقدار Reply To Message ID را برابر با شناسه پیام دریافتی قرار دهید:

{{$json.message.message_id}}

ارسال پیام به چند کاربر یا چند گروه

اگر لیستی از Chat IDها دارید، می‌توانید از نود Split In Batches یا Loop Over Items استفاده کنید و برای هر آیتم یک پیام جداگانه ارسال کنید.

• یک نود Set بسازید و لیست Chat IDها را آماده کنید.
• داده‌ها را با Item Lists یا Code به آیتم‌های جداگانه تبدیل کنید.
• نود Telegram را برای هر آیتم اجرا کنید.
• برای جلوگیری از محدودیت نرخ ارسال، بین ارسال‌ها از Wait استفاده کنید.

مدیریت دستورات ربات

برای مدیریت دستورهایی مثل /start، /help، /status و /report از نود Switch استفاده کنید. مقدار ورودی Switch می‌تواند متن پیام باشد:

{{$json.message.text}}

• اگر مقدار /start بود، پیام خوش‌آمدگویی ارسال شود.
• اگر مقدار /help بود، راهنمای استفاده ارسال شود.
• اگر مقدار /report بود، گزارش از دیتابیس خوانده و ارسال شود.
• اگر هیچ‌کدام نبود، پیام پیش‌فرض ارسال شود.

ترکیب با Code برای ساخت پیام پویا

گاهی متن پیام باید از چند فیلد مختلف ساخته شود. در این حالت می‌توانید از نود Code یا Set استفاده کنید.

{  "order_id": 1024,  "customer_name": "علی رضایی",  "total": 850000,  "status": "پرداخت شده"}

نمونه متن در فیلد Text نود Telegram:

<b>سفارش جدید</b>شماره سفارش: {{$json.order_id}}نام مشتری: {{$json.customer_name}}مبلغ: {{$json.total}} تومانوضعیت: {{$json.status}}

دانلود و پردازش فایل ارسال‌شده توسط کاربر

برای دریافت فایل از کاربر، ابتدا Telegram Trigger باید پیام دارای document، photo، audio یا video را دریافت کند. سپس File ID را به نود Telegram با عملیات Get File بدهید. بعد از دریافت فایل، می‌توانید آن را به Google Drive، S3، Email، OCR یا سرویس‌های پردازش سند ارسال کنید.

• Telegram Trigger: دریافت فایل کاربر
• Telegram Get File: گرفتن فایل یا مسیر فایل
• Google Drive: ذخیره فایل
• Telegram Send Message: ارسال پیام تأیید ذخیره‌سازی

استفاده از تلگرام به‌عنوان پنل مدیریتی

با ترکیب Inline Keyboard، Callback Query و Edit Message Text می‌توانید پنل مدیریتی ساده بسازید. برای مثال، مدیر در تلگرام دکمه مشاهده سفارش‌ها را می‌زند، N8N سفارش‌ها را از دیتابیس می‌خواند و با دکمه‌های تایید، لغو یا تغییر وضعیت نمایش می‌دهد.

بهینه‌سازی عملکرد و جلوگیری از ارسال تکراری

• برای جلوگیری از اجرای هم‌زمان چند عملیات، در سناریوهای حساس از Queue Mode یا تنظیمات Concurrency استفاده کنید.
• برای جلوگیری از ارسال پیام تکراری، شناسه update_id یا message_id را در دیتابیس ذخیره و قبل از پردازش بررسی کنید.
• برای ارسال انبوه، ارسال‌ها را دسته‌بندی کنید و بین هر دسته Wait قرار دهید.
• برای پیام‌های طولانی، متن را به چند بخش تقسیم کنید؛ محدودیت متن پیام تلگرام معمولاً 4096 کاراکتر است.
• برای گزارش‌های حجیم، به‌جای متن طولانی، فایل PDF یا CSV ارسال کنید.

محدودیت‌ها و خطاها

محدودیت‌های مهم

• بات نمی‌تواند به کاربری پیام بدهد که قبلاً ربات را Start نکرده یا با آن تعامل نداشته است.
• برای ارسال پیام به کانال، بات باید ادمین کانال باشد.
• برای دریافت بعضی پیام‌های گروهی، ممکن است لازم باشد Privacy Mode ربات را از BotFather غیرفعال کنید.
• تلگرام برای ارسال پیام محدودیت نرخ دارد. به‌صورت عملی، ارسال بیش از حد سریع پیام‌ها می‌تواند باعث خطای 429 شود.
• طول پیام متنی تلگرام محدود است و پیام‌های خیلی طولانی باید تقسیم شوند.
• حجم فایل‌های قابل ارسال و دانلود تابع محدودیت‌های Telegram Bot API و نسخه مورد استفاده است.
• در محیط Self-hosted، Webhook باید از اینترنت قابل دسترس باشد و معمولاً نیاز به HTTPS معتبر دارد.
• بات‌ها به تمام قابلیت‌های کاربر عادی تلگرام دسترسی ندارند؛ برای مثال نمی‌توانند بدون مجوز وارد گروه‌ها شوند یا پیام خصوصی را بدون شروع کاربر آغاز کنند.

خطای Bad Request: chat not found

این خطا معمولاً زمانی رخ می‌دهد که Chat ID اشتباه باشد، بات به گروه یا کانال اضافه نشده باشد، یا کاربر هنوز ربات را Start نکرده باشد.

• Chat ID را از خروجی Telegram Trigger بردارید.
• برای کانال از Username کانال مثل @my_channel یا Chat ID عددی صحیح استفاده کنید.
• مطمئن شوید بات عضو یا ادمین مقصد است.

خطای Forbidden: bot was blocked by the user

این خطا یعنی کاربر ربات را بلاک کرده است. در این حالت امکان ارسال پیام به کاربر وجود ندارد.

• این کاربر را از لیست ارسال حذف کنید.
• وضعیت خطا را در دیتابیس ذخیره کنید تا ارسال‌های بعدی برای او انجام نشود.

خطای Too Many Requests: retry after

این خطا به محدودیت نرخ ارسال مربوط است. تلگرام معمولاً مقدار retry_after را برمی‌گرداند که نشان می‌دهد چند ثانیه باید صبر کنید.

• بین ارسال‌ها از Wait استفاده کنید.
• ارسال انبوه را به دسته‌های کوچک تقسیم کنید.
• در صورت دریافت retry_after، مقدار آن را خوانده و ارسال بعدی را با تأخیر انجام دهید.

خطای Bad Request: can’t parse entities

این خطا زمانی رخ می‌دهد که متن پیام با Parse Mode انتخاب‌شده سازگار نباشد. برای مثال تگ HTML بسته نشده باشد یا در MarkdownV2 کاراکترهای خاص Escape نشده باشند.

• اگر از HTML استفاده می‌کنید، تگ‌ها را کامل و صحیح ببندید.
• از تگ‌های غیرمجاز HTML استفاده نکنید.
• برای متن‌های تولیدشده توسط کاربر، کاراکترهای خاص را پاک‌سازی کنید.
• در صورت نیاز Parse Mode را غیرفعال کنید.

خطای Webhook نامعتبر در Telegram Trigger

اگر Telegram Trigger رویدادها را دریافت نمی‌کند، معمولاً مشکل از Webhook است.

• آدرس N8N باید از اینترنت قابل دسترسی باشد.
• برای Self-hosted، دامنه و SSL معتبر تنظیم شود.
• اگر از تونل استفاده می‌کنید، آدرس تونل نباید تغییر کرده باشد.
• بررسی شود که بات هم‌زمان به Webhook دیگری متصل نباشد.

مشکل دریافت نکردن پیام‌های گروه

در گروه‌ها، Privacy Mode ممکن است باعث شود ربات فقط دستورها یا پیام‌هایی که مستقیماً به او اشاره دارند را دریافت کند.

• در BotFather وارد تنظیمات ربات شوید.
• گزینه Bot Settings و سپس Group Privacy را بررسی کنید.
• در صورت نیاز Privacy Mode را خاموش کنید.
• بات را از گروه حذف و دوباره اضافه کنید تا تنظیمات جدید اعمال شود.

ایده ها

• ربات ثبت سفارش تلگرامی: کاربر محصول را انتخاب کند، اطلاعات تماس را بفرستد، سفارش در Google Sheets یا دیتابیس ثبت شود و پیام تأیید دریافت کند.
• سیستم هشدار مانیتورینگ: وضعیت سرور، سایت یا API بررسی شود و در صورت اختلال، پیام فوری به گروه فنی ارسال شود.
• دستیار هوش مصنوعی در تلگرام: کاربر سوال خود را در تلگرام بفرستد، N8N آن را به مدل AI ارسال کند و پاسخ را در همان چت برگرداند.
• پنل تایید مدیریتی: درخواست‌های مرخصی، فاکتور یا سفارش با دکمه‌های تایید و رد در تلگرام برای مدیر ارسال شود و نتیجه در سیستم ثبت شود.
• ارسال گزارش خودکار: هر روز یا هر هفته گزارش فروش، موجودی، تیکت‌ها یا عملکرد کمپین‌ها به‌صورت پیام، فایل PDF یا Excel در تلگرام ارسال شود.

منابع و مستندات اصلی

• مستندات رسمی نود Telegram در N8N
• مستندات رسمی Telegram Trigger در N8N
• مستندات رسمی Telegram Bot API
• راهنمای قابلیت‌های Telegram Bots
• انجمن رسمی N8N Community
• مستندات Expressions در N8N