ساخت ربات تلگرام با n8n — قدم به قدم از صفر

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

هیچ تجربه‌ی قبلی لازم نیست. هر چیزی که لازم داشته باشید اینجا هست.

قبل از شروع

دو چیز لازم دارید: یک حساب تلگرام، و یک n8n در دسترس. اگر هنوز n8n ندارید، ساده‌ترین راه نصب با داکر است. اگر نمی‌دانید n8n چیست، اول این مقاله را بخوانید.

زمان لازم فقط 20 دقیقه!!

گام ۱ — ساختن ربات تلگرام و گرفتن توکن

ربات تلگرام را خود تلگرام می‌سازد، نه n8n. برای این کار یک ربات مخصوص هست به اسم BotFather.

1. در تلگرام، بالای صفحه بنویسید BotFather و روی نتیجه‌ای که تیک آبی دارد بزنید.
2. دکمه‌ی START پایین صفحه را بزنید.
3. بنویسید /newbot و بفرستید.
4. می‌پرسد اسم ربات چه باشد. هر چیزی بنویسید؛ همین اسم بالای گفت‌وگو دیده می‌شود. مثلاً ربات پشتیبانی من
5. حالا نام کاربری می‌خواهد. این یکی باید یکتا باشد و به bot ختم شود. مثلاً asrin_test_2026_bot. اگر گرفته شده باشد می‌گوید و باید دوباره امتحان کنید.

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

8123456789:AAF3xK9pQwErTyUiOpAsDfGhJkLzXcVbNm4

این توکن شماست. کپی‌اش کنید و یک جای امن بگذارید.

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

گام ۲ — ساختن فلوی ربات تلگرام در n8n

وارد n8n شوید. بالا سمت راست دکمه‌ای هست با عنوان Create Workflow — بزنیدش. یک بوم خالی می‌بینید با یک مستطیل خط‌چین وسطش که رویش نوشته Add first step.

بالای صفحه، جایی که نوشته My workflow، روی متن کلیک کنید و اسمش را بگذارید ربات تلگرام. نامگذاری  الان، شش ماه بعد که ده تا فلو دارید نجاتتان می‌دهد.

گام ۳ — گره اول: شنیدن پیام‌ها

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

حالا باید توکن را به n8n بدهید:

1. بالای پنل، کنار Credential to connect with، روی Create new credential بزنید.
2. در کادر Access Token همان رشته‌ای را که از BotFather گرفتید را قرار دهید.
3. دکمه‌ی Save را بزنید. اگر توکن درست باشد، یک تیک سبز با نوشته‌ی Connection tested successfully می‌بینید.

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

حالا پنجره‌ی اعتبارنامه را ببندید. در تنظیمات خود گره، بخشی هست به اسم Trigger On. تیک Message را بزنید و بقیه را رها کنید. یعنی: «هر وقت کسی پیام فرستاد، بیدار شو.»

اولین آزمایش

دکمه‌ی Execute step را بزنید. n8n می‌رود در حالت انتظار و می‌نویسد منتظر یک رویداد است.

حالا در تلگرام بروید سراغ ربات خودتان — همان نام کاربری که ساختید، مثلاً @asrin_test_2026_bot  و یک سلام بفرستید.

برگردید به n8n. باید داده‌ای شبیه این ببینید:

{
  "message": {
    "message_id": 4,
    "from": {
      "id": 987654321,
      "first_name": "اسرین",
      "username": "asrin"
    },
    "chat": {
      "id": 987654321,
      "type": "private"
    },
    "date": 1756600000,
    "text": "سلام"
  }
}

این همان JSON است. لازم نیست بنویسیدش، فقط باید بتوانید در آن دنبال چیزی بگردید. سه قسمت از آن را در گام بعد استفاده می‌کنیم:

• message.text — متنی که کاربر فرستاده
• message.chat.id — آدرس گفت‌وگو، برای اینکه بدانیم جواب را کجا بفرستیم
• message.from.first_name — اسم کوچک کاربر

اگر چیزی ندیدید، بخش خطاهای پایین صفحه را ببینید.

گام ۴ — گره دوم: ساختن جواب

روی علامت + سمت راست گره تلگرام کلیک کنید. در جستجو بنویسید Code و گره Code را انتخاب کنید.

در تنظیماتش، Mode را روی Run Once for All Items بگذارید و Language را روی JavaScript. حالا هرچه در کادر کد هست پاک کنید و این را بگذارید:

// پیام ورودی را از گره قبلی برمی‌داریم
const msg = $input.first().json.message;

// اگر کاربر اسم نداشت، یک جایگزین محترمانه
const name = msg.from.first_name || 'دوست من';
const text = (msg.text || '').trim();

let reply;

if (text === '/start') {
  reply = `سلام ${name}! خوش آمدی.\n` +
          `هر پیامی بفرستی جوابت را می‌دهم.\n` +
          `برای دیدن راهنما /help را بفرست.`;

} else if (text === '/help') {
  reply = `فعلاً دو دستور دارم:\n` +
          `/start شروع دوباره\n` +
          `/help همین راهنما`;

} else if (text === '') {
  reply = `${name} جان، فعلاً فقط متن می‌فهمم.`;

} else {
  reply = `${name} جان، پیامت را گرفتم:\n«${text}»`;
}

// خروجی برای گره بعدی
return [{
  json: {
    chatId: msg.chat.id,
    reply: reply
  }
}];

سه نکته درباره‌ی این کد:

$input.first().json یعنی «اولین داده‌ای که از گره قبلی آمد». اگر گره قبلی چند داده بدهد، اینجا فقط اولی را می‌گیریم — که برای ربات تلگرام درست است، چون هر بار یک پیام می‌آید.

آن || 'دوست من' یعنی «اگر این خالی بود، به‌جایش این را بگذار». بعضی کاربران تلگرام اسم ندارند و بدون این خط، ربات می‌نویسد «سلام undefined».

و return باید حتماً یک آرایه برگرداند که داخلش شیءهایی با کلید json باشند. اگر این ساختار را رعایت نکنید n8n خطا می‌دهد. این رایج‌ترین اشتباه تازه‌کارهاست.

حالا Execute step را بزنید. باید در خروجی دو فیلد ببینید: chatId و reply — با متن جوابی که ساخته شده.

گام ۵ — گره سوم: فرستادن

باز هم روی + بزنید، بنویسید Telegram و این بار خودِ Telegram را انتخاب کنید (نه Trigger).

تنظیماتش:

• Credential: همانی که در گام ۳ ساختید، از فهرست انتخاب کنید. دوباره نسازید.
• Resource: Message
• Operation: Send Message
• Chat ID: اینجا حواستان باشد. کنار کادر یک کلید کوچک هست که بین Fixed و Expression جابه‌جا می‌شود. روی Expression بگذارید و بنویسید: {{ $json.chatId }}
• Text: این هم روی Expression: {{ $json.reply }}

اگر یادتان برود کلید را روی Expression بگذارید، ربات عیناً متن {{ $json.reply }} را می‌فرستد. اتفاق بامزه‌ای است و همه یک بار تجربه‌اش می‌کنند.

Execute step را بزنید. باید همین حالا در تلگرام پیام بگیرید.

گام ۶ — فعال کردن

تا اینجا ربات فقط وقتی کار می‌کند که شما دکمه بزنید. برای اینکه دائمی شود:

1. بالا سمت راست، کلید Publish را بزنید تا فعال شود.
2. یک پنجره تأیید می‌خواهد؛ قبول کنید.

حالا ببندید و از تلگرام یک پیام بفرستید. جواب می‌آید — بدون اینکه n8n باز باشد.

یک تفاوت که خیلی‌ها را گیج می‌کند: در حالت آزمایش، n8n منتظر یک پیام می‌ماند و بعد متوقف می‌شود. در حالت فعال، همیشه گوش می‌دهد. اگر فلو را عوض کردید، حتماً Save بزنید و دوباره Publish کنید وگرنه نسخه‌ی قدیمی اجرا می‌شود.

وقتی ربات تلگرام کار نمی‌کند

Bad Request: chat not found
تلگرام اجازه نمی‌دهد ربات اول شروع کند؛ کاربر باید اول پیام بدهد. در تلگرام ربات را باز کنید و یک بار /start بزنید.

409 Conflict: terminated by other getUpdates request
دو جا همزمان با یک توکن گوش می‌دهند. معمولاً یک فلوی قدیمی هنوز فعال است، یا همان توکن را در ابزار دیگری هم گذاشته‌اید. یکی را غیرفعال کنید.

can't parse entities
در تنظیمات گره تلگرام، زیر Additional Fields، گزینه‌ی Parse Mode را روی None بگذارید. این یعنی متن خام برود و تلگرام دنبال قالب‌بندی نگردد.

هیچ اتفاقی نمی‌افتد.
اول ببینید فلو فعال است. بعد در منوی بالای صفحه، بخش Executions را باز کنید — تاریخچه‌ی هر اجراست. اگر اجرایی ثبت شده ولی قرمز است، رویش کلیک کنید تا ببینید کدام گره شکسته.

راه بدون کد: گره Switch

اگر ترجیح می‌دهید جاوااسکریپت ننویسید، می‌شود همان منطق را با گره Switch ساخت. Switch یک ورودی می‌گیرد و بسته به شرط، به یکی از چند خروجی می‌فرستد.

به‌جای گره Code، یک Switch بگذارید با Mode روی Rules و دو قانون:

• قانون اول: مقدار {{ $json.message.text }} برابر باشد با /start ← خروجی ۱
• قانون دوم: هر چیز دیگر ← خروجی Fallback

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

مزیتش این است که چیزی برای نوشتن ندارید. عیبش این است که برای هر حالت تازه باید یک شاخه‌ی جدید بسازید و بوم به‌سرعت شلوغ می‌شود. برای بیشتر از سه چهار حالت، همان چند خط کد تمیزتر است.

قدم بعدی

این ربات تلگرام هنوز چیزی به یاد نمی‌آورد؛ هر پیام برایش تازه است. سه جهت برای ادامه دادن:

• حافظه: یک گره پایگاه داده اضافه کنید تا بداند این کاربر قبلاً چه گفته.
• دکمه: در Additional Fields گره تلگرام می‌توانید Reply Markup بگذارید تا به‌جای تایپ، دکمه بزنند.
• هوش: بین Code و Telegram یک گره مدل زبانی بگذارید تا جواب‌ها ثابت نباشند.

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

بیشتر بخوانید

• نصب n8n روی لپ‌تاپ و با داکر — اگر هنوز n8n ندارید
• نصب روی سرور اوبونتو — برای وقتی که وب‌هوک باید همیشه در دسترس باشد
• جیسون چیست؟ — همان ساختاری که در خروجی گره تلگرام دیدید
• مقدمات جاوااسکریپت — برای فهمیدن کد داخل گره Code