Telegram Bot API

اتصال n8n به تلگرام: وصل کردن ربات، اجرای ورک‌فلو و ارسال پیام

· 8 دقیقه مطالعه

برای اتصال n8n به تلگرام فقط یک چیز از تلگرام لازم دارید: توکن ربات. آن را در n8n به عنوان Access Token یک credential تلگرام ذخیره کنید، بعد با نود Telegram Trigger ورک‌فلوها را با پیام‌های ورودی اجرا کنید و با نود Telegram به یک چت آیدی پیام بفرستید. تریگر از طریق وب هوک Bot API کار می‌کند، پس نمونه‌ی n8n شما باید روی یک آدرس HTTPS عمومی در دسترس باشد. در این راهنما مراحل راه‌اندازی، تنظیماتی که n8n خودمیزبان (self-hosted) لازم دارد و رایج‌ترین خطاها را می‌بینید.

یکپارچه‌سازی n8n با تلگرام چطور کار می‌کند

نودچه کاری انجام می‌دهدBot API پشت صحنهHTTPS عمومی لازم است؟
Telegram Triggerورک‌فلو را با یک آپدیت شروع می‌کند: پیام، فشردن دکمه، پست کانال و غیرهsetWebhook، بعد تلگرام آپدیت‌ها را با POST به n8n می‌فرستدبله
Telegramپیام می‌فرستد و ویرایش می‌کند، فایل می‌فرستد، به callback query جواب می‌دهد، اطلاعات چت را می‌خواندsendMessage، sendPhoto، editMessageText، answerCallbackQuery…خیر، فقط درخواست خروجی

چون تریگر از وب هوک استفاده می‌کند، قوانین وب هوک Bot API برای n8n هم صدق می‌کند: فقط HTTPS، پورت‌های 443، 80، 88 یا 8443، یک آدرس وب هوک برای هر ربات، و عدم امکان getUpdates تا وقتی وب هوک تنظیم است.

مرحله‌ی 1: ساخت ربات و گرفتن توکن

  1. @BotFather را باز کنید، /newbot را بفرستید، یک نام نمایشی و یک یوزرنیم که به bot ختم شود انتخاب کنید.
  2. توکنی را که BotFather برمی‌گرداند کپی کنید. شکلی شبیه 123456789:AAEexampleTokenReplaceWithYours دارد. برای ربات موجود، /mybots ← ربات شما ← API Token را باز کنید.
  3. قبل از وارد کردن توکن در هر جایی، آن را بررسی کنید:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getMe"

توکن معتبر "ok": true را همراه با مشخصات ربات برمی‌گرداند؛ توکن اشتباه 401 Unauthorized برمی‌گرداند. همین بررسی را می‌توانید در getMe در Bot API Tester انجام دهید. جزئیات پیدا کردن، بررسی و باطل کردن توکن در راهنمای توکن ربات تلگرام آمده است؛ اگر هنوز ربات ندارید، از آموزش ساخت ربات تلگرام شروع کنید.

مرحله‌ی 2: افزودن credential تلگرام در n8n

n8n فقط با توکن ربات به تلگرام احراز هویت می‌کند. یک credential جدید از نوع Telegram بسازید و توکن را در فیلد Access Token آن بگذارید. نود Telegram و نود Telegram Trigger از یک نوع credential استفاده می‌کنند، پس برای هر ربات یک credential کافی است.

با توکن مثل رمز عبور رفتار کنید: هر کسی آن را داشته باشد ربات را کنترل می‌کند. اگر لو رفت، در @BotFather باطلش کنید و credential را در n8n به‌روز کنید.

مرحله‌ی 3: دریافت آپدیت با وب هوک Telegram Trigger در n8n

یک نود Telegram Trigger اضافه کنید، credential خود را انتخاب کنید و مشخص کنید کدام آپدیت‌ها ورک‌فلو را شروع کنند. انتخاب‌های رایج Message برای پیام‌های ورودی و Callback Query برای فشردن دکمه‌های اینلاین است؛ * یعنی همه‌ی آپدیت‌ها به جز آپدیت‌های اعضای چت و ری‌اکشن‌ها، که با پیش‌فرض Bot API یکی است. این نود را می‌توان به چت آیدی‌ها یا یوزر آیدی‌های خاص محدود کرد و می‌تواند تصاویر و فایل‌های پیوست را هم دانلود کند.

وقتی ورک‌فلو را تست یا منتشر می‌کنید، n8n برای ربات شما setWebhook را با آدرسی از نمونه‌ی خودش صدا می‌زند. از آن به بعد تلگرام هر آپدیت را با HTTPS POST به n8n می‌فرستد. دو نتیجه از این موضوع می‌گیریم:

در دسترس قرار دادن n8n خودمیزبان روی HTTPS

n8n Cloud از قبل آدرس HTTPS عمومی دارد. نمونه‌ی خودمیزبان آدرس‌های وب هوک را از پروتکل، هاست و پورت خودش می‌سازد که پشت reverse proxy یا روی localhost معمولاً یک آدرس http:// می‌شود و تلگرام آن را رد می‌کند. راه‌حل:

  1. n8n را پشت یک reverse proxy (nginx، Caddy، Traefik و غیره) بگذارید که TLS را با گواهی معتبر روی پورت 443 مدیریت کند.
  2. آدرس عمومی را به n8n بگویید. نسخه‌های فعلی n8n از N8N_WEBHOOK_URL استفاده می‌کنند؛ WEBHOOK_URL قدیمی از n8n 2.35.0 منسوخ شده اما هنوز خوانده می‌شود، و نسخه‌های قبل از 2.30.0 فقط WEBHOOK_URL را می‌شناسند.
  3. N8N_PROXY_HOPS=1 را تنظیم کنید و هدرهای X-Forwarded-For، X-Forwarded-Host و X-Forwarded-Proto را از پراکسی عبور دهید.
  4. پراکسی WebSocket را فعال کنید، وگرنه ادیتور هنگام انتظار برای رویداد تست تریگر ممکن است گیر کرده به نظر برسد.
  5. n8n را ری‌استارت کنید و ورک‌فلو را دوباره فعال کنید تا تریگر آدرس HTTPS جدید را ثبت کند.
# n8n پشت reverse proxy که https://n8n.example.com را سرو می‌کند
export N8N_WEBHOOK_URL=https://n8n.example.com/
export N8N_PROXY_HOPS=1
# نسخه‌های n8n قبل از 2.30.0: به جای آن از WEBHOOK_URL استفاده کنید
# export WEBHOOK_URL=https://n8n.example.com/

برای توسعه‌ی محلی، تونلی که یک هاست‌نیم HTTPS عمومی به شما می‌دهد هم به همین شکل کار می‌کند: آن هاست‌نیم را در N8N_WEBHOOK_URL بگذارید. یادتان باشد هر بار آدرس تونل عوض شود، وب هوک از کار می‌افتد.

بررسی وب هوکی که تلگرام برای ربات شما ثبت کرده

وقتی تریگر ساکت می‌ماند، مستقیم با getWebhookInfo از تلگرام بپرسید. این متد آدرس ثبت‌شده، تعداد آپدیت‌های در انتظار و آخرین خطای تحویل را نشان می‌دهد. این اسکریپت یک تشخیص کوتاه چاپ می‌کند:

import os
import requests

TOKEN = os.environ["BOT_TOKEN"]  # همان توکنی که در credential n8n است
API = f"https://api.telegram.org/bot{TOKEN}"

data = requests.get(f"{API}/getWebhookInfo", timeout=10).json()
if not data["ok"]:
    raise SystemExit(f"{data['error_code']} {data['description']}")  # 401: توکن اشتباه

info = data["result"]
print("Webhook URL:", info["url"] or "(خالی: هیچ Telegram Trigger فعالی نیست)")
print("Pending updates:", info["pending_update_count"])
if info["url"] and not info["url"].startswith("https://"):
    print("مشکل: تلگرام به آدرس HTTPS نیاز دارد")
if "last_error_message" in info:
    print("آخرین خطای تحویل:", info["last_error_message"])
const TOKEN = process.env.BOT_TOKEN; // همان توکنی که در credential n8n است
const API = `https://api.telegram.org/bot${TOKEN}`;

const data = await (await fetch(`${API}/getWebhookInfo`)).json();
if (!data.ok) {
  console.error(`${data.error_code} ${data.description}`); // 401: توکن اشتباه
  process.exit(1);
}

const info = data.result;
console.log("Webhook URL:", info.url || "(خالی: هیچ Telegram Trigger فعالی نیست)");
console.log("Pending updates:", info.pending_update_count);
if (info.url && !info.url.startsWith("https://")) {
  console.log("مشکل: تلگرام به آدرس HTTPS نیاز دارد");
}
if (info.last_error_message) {
  console.log("آخرین خطای تحویل:", info.last_error_message);
}

نسخه‌ی جاوااسکریپت را با نام check.mjs ذخیره و با Node.js 18 یا جدیدتر اجرا کنید. نتیجه را این‌طور بخوانید: آدرسی از سرویس دیگر یعنی چیز دیگری وب هوک ربات را تصاحب کرده؛ بالا رفتن pending_update_count همراه با last_error_message یعنی تلگرام به n8n نمی‌رسد یا n8n با خطا جواب می‌دهد. بدون کد، از getWebhookInfo در Bot API Tester استفاده کنید.

مرحله‌ی 4: ارسال پیام تلگرام از n8n

یک نود Telegram اضافه کنید، ریسورس Message و عملیات Send Message را انتخاب کنید، credential را برگزینید و دو فیلد را پر کنید:

دو پیش‌فرض معمولاً غافلگیرکننده‌اند. نود خط This message was sent automatically with n8n را به پیام اضافه می‌کند؛ برای حذف آن گزینه‌ی Append n8n Attribution را در فیلدهای اضافه خاموش کنید. همچنین parse mode نود به طور پیش‌فرض HTML است، پس در متن پویا <، > و & را به صورت &lt;، &gt; و &amp; escape کنید، وگرنه تلگرام پیام را با خطای can't parse entities رد می‌کند.

قبل از وصل کردن چت آیدی به ورک‌فلو، می‌توانید با یک درخواست در sendMessage در Bot API Tester مطمئن شوید کار می‌کند. برای ارسال در کانال، اول ربات را ادمین کانال کنید. تلگرام در ارسال انبوه حدود 30 پیام در ثانیه و در یک چت حدود یک پیام در ثانیه اجازه می‌دهد، پس حلقه‌های ارسال همگانی را کند کنید؛ محدودیت‌های Telegram Bot API را ببینید.

پیدا کردن چت آیدی

ساده‌ترین منبع خود تریگر است: ورک‌فلو را اجرا کنید، به ربات پیام دهید و message.chat.id را در خروجی تریگر بخوانید. کاربران آیدی مثبت دارند، گروه‌ها منفی، و سوپرگروه‌ها و کانال‌ها شکلی مثل -1001234567890 دارند. اگر getUpdates را ترجیح می‌دهید، آن را قبل از فعال شدن هر Telegram Trigger برای این ربات صدا بزنید؛ تا وقتی وب هوک تنظیم است با 409 Conflict شکست می‌خورد. همه‌ی روش‌ها، از جمله گروه‌ها، کانال‌ها و تاپیک‌های فوروم، در آموزش پیدا کردن چت آیدی تلگرام آمده است.

رفع خطاهای n8n و تلگرام

نشانهعلتراه‌حل
Bad Request: bad webhook: An HTTPS URL must be provided for webhookn8n یک آدرس http:// ثبت کرده: localhost یا پراکسی بدون TLSTLS را در پراکسی مدیریت کنید و N8N_WEBHOOK_URL (یا WEBHOOK_URL) را روی آدرس HTTPS بگذارید
خطای bad webhook درباره‌ی پورتآدرس عمومی از پورتی غیر از 443، 80، 88 یا 8443 استفاده می‌کندn8n را از طریق پراکسی روی 443 در دسترس قرار دهید
409 Conflict از getUpdatesیک Telegram Trigger وب هوک را ثبت‌شده نگه می‌داردورک‌فلو را غیرفعال کنید و deleteWebhook را صدا بزنید، یا چت آیدی را از تریگر بردارید
ورک‌فلو فقط در تست یا فقط در حالت منتشرشده کار می‌کندآدرس‌های وب هوک تست و production جای همدیگر را می‌گیرندهنگام تست از انتشار خارج کنید یا ربات تست جداگانه داشته باشید
تریگر بعد از فعال شدن ورک‌فلوی دیگر از کار افتادتریگر دوم یا سرویس دیگری با همان توکن setWebhook را صدا زدهیک تریگر برای هر ربات؛ آدرس را با getWebhookInfo بررسی کنید
ادیتور روی “waiting for trigger event” گیر کردهreverse proxy بدون پشتیبانی WebSocketپراکسی WebSocket را فعال کنید و ورک‌فلو را دوباره باز کنید
برای پیام‌های گروه آپدیتی نمی‌رسدprivacy mode: در گروه‌ها ربات فقط دستورات مخصوص خودش، ریپلای‌ها به خودش و پیام‌های سرویسی را می‌گیردprivacy را با /setprivacy خاموش کنید یا ربات را ادمین کنید
401 Unauthorizedتوکن اشتباه یا باطل‌شده در credentialآن را با getMe بررسی کنید و توکن فعلی را وارد کنید
400 Bad Request: chat not found هنگام ارسالچت آیدی اشتباه، یا چتی که ربات به آن دسترسی ندارد: کاربر هرگز ربات را استارت نکرده یا ربات در گروه نیستآیدی را دوباره بررسی کنید؛ از کاربر بخواهید /start بفرستد یا ربات را به گروه اضافه کنید

برای شروع از یک وضعیت تمیز، ورک‌فلو را غیرفعال کنید، deleteWebhook را صدا بزنید، مطمئن شوید getWebhookInfo یک url خالی نشان می‌دهد و بعد ورک‌فلو را دوباره فعال کنید تا n8n آدرسش را از نو ثبت کند. برای سازوکار کلی وب هوک (secret token، تلاش مجدد، گواهی‌ها) آموزش وب هوک ربات تلگرام را ببینید.

پرسش‌های متداول

چطور تلگرام را به n8n وصل کنم؟

با @BotFather یک ربات بسازید، توکن آن را کپی کنید و در n8n به عنوان Access Token یک credential تلگرام ذخیره کنید. برای دریافت پیام‌ها از نود Telegram Trigger و برای ارسال از نود Telegram استفاده کنید؛ هر دو نود از همان credential استفاده می‌کنند.

چرا Telegram Trigger در n8n خطای “An HTTPS URL must be provided for webhook” می‌دهد؟

تریگر با setWebhook وب هوک ثبت می‌کند و تلگرام فقط آدرس‌های HTTPS عمومی را می‌پذیرد. اگر n8n روی http://localhost یا پشت پراکسی بدون TLS اجرا می‌شود، آدرس HTTPS عمومی نمونه‌ی خود را در N8N_WEBHOOK_URL (در نسخه‌های قدیمی WEBHOOK_URL) بگذارید و TLS را در reverse proxy مدیریت کنید.

آیا دو ورک‌فلوی n8n می‌توانند از تریگر یک ربات تلگرام استفاده کنند؟

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

چرا بعد از راه‌اندازی n8n، getUpdates خطای 409 Conflict می‌دهد؟

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

آیا فقط برای ارسال پیام تلگرام از n8n به آدرس HTTPS عمومی نیاز دارم؟

خیر. نود Telegram فقط درخواست خروجی به api.telegram.org می‌فرستد، پس ارسال از یک n8n محلی هم کار می‌کند. HTTPS عمومی فقط برای دریافت آپدیت با Telegram Trigger لازم است.

چت آیدی را برای نود Telegram در n8n از کجا پیدا کنم؟

آن را از خروجی تریگر (message.chat.id) بردارید، یا قبل از فعال شدن تریگر به ربات پیام دهید و getUpdates را صدا بزنید. کانال‌های عمومی @channelusername را هم می‌پذیرند.

ساخت ربات تلگرام: آموزش قدم‌به‌قدم از BotFather تا اولین پیام با Python

ساخت ربات تلگرام قدم‌به‌قدم: ساخت ربات در BotFather، گرفتن توکن، تست با getMe، پیدا کردن chat id و ارسال اولین پیام با curl و Python.

دیپلوی ربات تلگرام: راه‌اندازی روی VPS، داکر و هاست Serverless

آموزش دیپلوی و هاست ربات تلگرام: polling یا وب هوک، سرویس systemd روی VPS، داکر، Cloudflare Workers با secret_token و چک‌لیست راه‌اندازی.

Telegram Bot API 10.0 تا 10.5: تنظیمات ربات، ویجت‌ها، پیام‌های rich و ephemeral، حالت مهمان و بیشتر

تغییرات Telegram Bot API 10.0 تا 10.5: متد setMySettings و BotFullInfo، ویجت‌های HTML، پیام‌های rich و ephemeral و حالت مهمان، همراه با مثال JSON.

خطاهای Telegram Bot API: معنی هر خطا و روش رفع آن

خطاهای ربات تلگرام به زبان ساده: 400 chat not found، 403 bot was blocked by the user، 409 Conflict و 429 retry_after؛ علت، راه حل و کد مدیریت خطا.

محدودیت‌های Telegram Bot API: نرخ ارسال، خطای 429، حجم فایل و طول پیام

محدودیت‌های Telegram Bot API به زبان ساده: 30 پیام در ثانیه، 1 پیام در ثانیه در هر چت، 20 در دقیقه در گروه، مدیریت خطای 429 و محدودیت حجم فایل.

دستورات ربات تلگرام: setMyCommands، اسکوپ دستورات و دیپ‌لینک /start

تنظیم دستورات ربات تلگرام: /setcommands در @BotFather، متد setMyCommands با اسکوپ و زبان، پارامتر دیپ‌لینک /start و دستور /cmd@bot در گروه‌ها.

کیبورد ربات تلگرام: دکمه شیشه‌ای (inline keyboard)، دکمه‌های callback و reply keyboard

ساخت دکمه شیشه‌ای ربات تلگرام: inline keyboard با callback_data، پاسخ با answerCallbackQuery، ویرایش پیام بعد از کلیک، reply keyboard و ForceReply.

ارسال پیام با ربات تلگرام از طریق API تلگرام (sendMessage)

آموزش ارسال پیام با ربات تلگرام از طریق API تلگرام: متد sendMessage با curl، Python و JavaScript، قالب‌بندی HTML و MarkdownV2، دکمه شیشه‌ای و رفع خطاها.

توکن ربات تلگرام: چیست، چطور بگیریم، بررسی و باطل کنیم

توکن ربات تلگرام چیست و از کجا بگیریم؟ گرفتن توکن از BotFather، پیدا کردن توکن ربات قبلی، تست با getMe، باطل کردن توکن لو رفته و نگهداری امن آن.

وب هوک ربات تلگرام: راه‌اندازی setWebhook، بررسی و رفع خطا

آموزش ست وب هوک تلگرام با setWebhook: پیش‌نیازهای HTTPS و پورت‌ها، secret_token، بررسی با getWebhookInfo، حذف وب هوک و رفع خطاهای رایج مثل 409.

چت آیدی تلگرام: چیست، کجاست و چطور chat id کاربر، گروه و کانال را پیدا کنیم

چت آیدی تلگرام کجاست؟ پیدا کردن chat_id کاربر، گروه، سوپرگروه، کانال و تاپیک با getUpdates، معنی آیدی‌های منفی و رفع مشکل نتیجه خالی و خطای 409.

ربات اینلاین تلگرام: فعال کردن حالت inline و پاسخ به کوئری‌ها

ساخت ربات اینلاین تلگرام: فعال کردن حالت inline با @BotFather یا setMySettings، دریافت آپدیت inline_query و پاسخ با answerInlineQuery.

پرداخت با Telegram Stars در ربات: فاکتور، پیش‌پرداخت، بازپرداخت و اشتراک

دریافت پرداخت با استارز تلگرام در ربات: sendInvoice با ارز XTR، پاسخ به pre_checkout_query، successful_payment، بازپرداخت و اشتراک با کد پایتون و JS.

سرور تست تلگرام: چطور ربات را در محیط تست تلگرام تست کنیم

سرور تست تلگرام برای ربات‌ها: ورود به محیط تست، ساخت ربات تست در BotFather، فراخوانی Bot API با مسیر /test/ و سوییچ TEST در تستر ما.

ویجت تلگرام برای سایت: ورود با تلگرام، جاسازی پست، کامنت‌ها و دکمه اشتراک‌گذاری

ورود با تلگرام در سایت با Telegram Login (OIDC) و ویجت قدیمی همراه کد بررسی hash، جاسازی پست کانال، ویجت کامنت و دکمه اشتراک‌گذاری تلگرام.

مرجع API جاوااسکریپت TelegramWidget: رویدادها، کدهای خطا و محدودیت‌ها

مرجع API جاوااسکریپت ویجت تلگرام: ویژگی‌ها، request()، رویدادها، کدهای خطا، متغیرهای CSS، widget_query و answerWidgetQuery و همه محدودیت‌ها.

مثال ویجت تلگرام: کد کامل HTML و ربات پایتون

مثال‌های کامل ویجت تلگرام با کد: کارت سفارش ثابت، شمارنده با widget_query، نظرسنجی زنده با ویجت اشتراکی و پیش‌نمایش در مرورگر با ربات پایتون.

ویجت تلگرام چیست؟ HTML تعاملی داخل پیام‌های ربات

ویجت تلگرام در Bot API 10.4 چیست؟ ارسال با sendWidget، وضعیت chat_data و public_data، محدودیت‌ها، جاهایی که فعلاً کار می‌کند و تفاوت با مینی اپ.

تست مینی اپ تلگرام: از mock در مرورگر تا اجرای واقعی در تلگرام

تست مینی اپ تلگرام قدم به قدم: حالت mock در مرورگر، اجرای localhost با تونل HTTPS، محیط تست، DevTools در هر پلتفرم و اعتبارسنجی initData در سرور.