اگر می‌خواهید ربات تلگرام با Node.js بسازید، یکی از گزینه‌های محبوب استفاده از کتابخانه Telegraf است. Telegraf یک Framework برای توسعه Telegram Bot با JavaScript و TypeScript است و امکاناتی مانند مدیریت Commandها، پیام‌ها، Callback Queryها، Middleware و Session را در اختیار توسعه‌دهنده قرار می‌دهد.

در این آموزش، یک Telegram Bot با Node.js و Telegraf را از صفر ایجاد می‌کنیم و مرحله‌به‌مرحله آن را توسعه می‌دهیم.

در پایان این مقاله، Bot ما می‌تواند:

• به /start پاسخ دهد.
• Commandهای مختلف را مدیریت کند.
• پیام‌های متنی کاربران را دریافت کند.
• برای کاربر Keyboard نمایش دهد.
• به Inline Keyboard پاسخ دهد.
• اطلاعات کاربر را دریافت کند.
• خطاها را مدیریت کند.
• Token را به شکل امن از Environment Variable دریافت کند.
• برای توسعه بیشتر آماده باشد.

اطلاعات سئو مقاله

کلمه کلیدی اصلی:

ساخت ربات تلگرام با Node.js

کلمات کلیدی فرعی:

• آموزش ساخت ربات تلگرام
• ساخت Telegram Bot با Node.js
• ساخت ربات تلگرام با JavaScript
• آموزش Telegraf
• Node.js Telegram Bot
• Telegraf Node.js
• Telegram Bot API
• ساخت بات تلگرام
• آموزش ساخت ربات تلگرام با جاوا اسکریپت

عنوان SEO پیشنهادی:

آموزش ساخت ربات تلگرام با Node.js و Telegraf از صفر

Meta Description پیشنهادی:

در این آموزش یاد می‌گیرید چگونه با Node.js و Telegraf یک ربات تلگرام بسازید، Command و Message مدیریت کنید، Keyboard ایجاد کنید و Bot خود را اجرا کنید.

URL پیشنهادی:

/telegram-bot-nodejs-telegraf/

Telegraf چیست؟

Telegraf یک Framework برای ساخت Telegram Bot با JavaScript و TypeScript است.

به جای اینکه تمام درخواست‌های HTTP مربوط به Telegram Bot API را به صورت دستی مدیریت کنیم، Telegraf یک API سطح بالاتر در اختیار ما قرار می‌دهد.

به عنوان مثال، به جای اینکه برای مدیریت /start خودمان Updateهای Telegram را بررسی کنیم، می‌توانیم بنویسیم:

bot.start((ctx) => {
    ctx.reply("سلام!");
});

این سادگی یکی از دلایل محبوبیت Telegraf در پروژه‌های Node.js است.

چرا از Node.js و Telegraf استفاده کنیم؟

ترکیب Node.js و Telegraf برای ساخت Botهای Telegram چند مزیت مهم دارد.

۱. استفاده از JavaScript

اگر با JavaScript آشنا باشید، برای شروع نیازی به یادگیری یک زبان جدید ندارید.

۲. اکوسیستم بزرگ npm

می‌توانیم Bot را به سرویس‌ها و کتابخانه‌های مختلف متصل کنیم:

Telegram Bot
     ↓
Node.js
     ↓
npm packages
     ↓
Database / API / AI / Payment

۳. Middleware

Telegraf معماری Middleware دارد که برای پروژه‌های بزرگ بسیار کاربردی است.

۴. پشتیبانی از TypeScript

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

۵. توسعه آسان

مدیریت Commandها و پیام‌ها نسبتاً ساده است و می‌توانیم Bot را مرحله‌به‌مرحله توسعه دهیم.

پیش‌نیازهای این آموزش

قبل از شروع، موارد زیر را نصب کنید:

• Node.js
• npm
• Telegram
• VS Code یا ویرایشگر مشابه
• دانش مقدماتی JavaScript

برای بررسی نصب Node.js:

node --version

و برای npm:

npm --version

اگر هر دو دستور نسخه‌ای مانند زیر نمایش دهند، آماده هستید:

v22.x.x
10.x.x

نسخه دقیق می‌تواند متفاوت باشد.

مرحله اول: ساخت Bot با BotFather

برای ساخت Telegram Bot ابتدا باید Bot خود را در Telegram ایجاد کنیم.

در Telegram، BotFather را باز کنید:

@BotFather

سپس دستور زیر را ارسال کنید:

/newbot

BotFather از شما یک نام برای Bot می‌خواهد.

مثلاً:

My Node.js Bot

سپس Username را انتخاب کنید:

my_nodejs_example_bot

اگر Username آزاد باشد، BotFather یک Bot Token به شما می‌دهد.

Token چیزی شبیه این خواهد بود:

123456789:AAxxxxxxxxxxxxxxxxxxxxxxxx

این Token بسیار مهم است.

نکته امنیتی

Token را مانند Password در نظر بگیرید.

آن را:

• داخل GitHub قرار ندهید.
• در Frontend قرار ندهید.
• در Screenshot منتشر نکنید.
• در کد عمومی قرار ندهید.

اگر شخص دیگری Token شما را داشته باشد، می‌تواند به Bot شما دسترسی پیدا کند.

مرحله دوم: ایجاد پروژه Node.js

یک پوشه برای پروژه ایجاد کنید:

mkdir telegram-telegraf-bot
cd telegram-telegraf-bot

سپس:

npm init -y

این دستور فایل package.json را ایجاد می‌کند.

ساختار پروژه در این مرحله:

telegram-telegraf-bot/
└── package.json

مرحله سوم: نصب Telegraf

اکنون Telegraf را نصب کنید:

npm install telegraf

پس از نصب، package.json شما شامل dependency مربوط به Telegraf خواهد شد.

مرحله چهارم: نصب dotenv

برای نگهداری امن Token بهتر است از Environment Variable استفاده کنیم.

پکیج dotenv را نصب کنید:

npm install dotenv

اکنون:

telegram-telegraf-bot/
├── node_modules/
├── package.json
├── package-lock.json
└── bot.js

مرحله پنجم: ایجاد فایل .env

در Root پروژه فایل زیر را ایجاد کنید:

.env

داخل آن بنویسید:

BOT_TOKEN=YOUR_TELEGRAM_BOT_TOKEN

Token واقعی خود را جایگزین کنید.

مثلاً:

BOT_TOKEN=123456789:AAxxxxxxxxxxxxxxxx

مرحله ششم: ایجاد .gitignore

اگر از Git استفاده می‌کنید، فایل .gitignore ایجاد کنید:

node_modules/
.env

این کار باعث می‌شود Token شما به صورت تصادفی Commit نشود.

مرحله هفتم: ساخت اولین Bot با Telegraf

فایل bot.js را ایجاد کنید.

کد زیر اولین Bot ماست:

require("dotenv").config();

const { Telegraf } = require("telegraf");

const bot = new Telegraf(process.env.BOT_TOKEN);

bot.start((ctx) => {
    ctx.reply("سلام! 👋 به ربات من خوش آمدید.");
});

bot.launch();

console.log("Bot is running...");

اکنون Bot را اجرا کنید:

node bot.js

اگر خطایی مشاهده نکردید، Bot شما در حال اجراست.

در Telegram وارد Bot خود شوید و:

/start

را ارسال کنید.

باید پاسخ زیر را دریافت کنید:

سلام! 👋 به ربات من خوش آمدید.

تبریک! اولین Telegram Bot با Node.js و Telegraf شما اجرا شده است.

بررسی کد Bot

بیایید کد را خط‌به‌خط بررسی کنیم.

بارگذاری .env

require("dotenv").config();

این خط باعث می‌شود متغیرهای فایل .env در process.env در دسترس باشند.

بنابراین:

process.env.BOT_TOKEN

Token ربات را در اختیار برنامه قرار می‌دهد.

Import کردن Telegraf

const { Telegraf } = require("telegraf");

در اینجا کلاس Telegraf را از پکیج نصب‌شده دریافت می‌کنیم.

ساخت Bot

const bot = new Telegraf(process.env.BOT_TOKEN);

یک Instance جدید از Bot می‌سازیم و Token را به آن می‌دهیم.

مدیریت /start

کد زیر:

bot.start((ctx) => {
    ctx.reply("سلام! 👋 به ربات من خوش آمدید.");
});

به Bot می‌گوید:

وقتی کاربر /start را ارسال کرد، این تابع را اجرا کن.

پارامتر ctx مخفف Context است و اطلاعات مربوط به Update فعلی را در اختیار ما قرار می‌دهد.

اجرای Bot

در نهایت:

bot.launch();

Bot را اجرا می‌کند.

اضافه کردن Commandهای بیشتر

حال می‌توانیم Commandهای بیشتری اضافه کنیم.

مثلاً:

bot.command("help", (ctx) => {
    ctx.reply(
        "دستورات موجود:\n\n" +
        "/start - شروع ربات\n" +
        "/help - راهنما\n" +
        "/about - درباره ربات"
    );
});

bot.command("about", (ctx) => {
    ctx.reply(
        "این ربات با Node.js و Telegraf ساخته شده است."
    );
});

اکنون Bot سه Command دارد:

/start
/help
/about

دریافت پیام‌های متنی

Telegraf امکان مدیریت انواع مختلف Update را فراهم می‌کند.

برای دریافت پیام متنی می‌توانیم بنویسیم:

bot.on("text", (ctx) => {
    ctx.reply(`شما گفتید: ${ctx.message.text}`);
});

اگر کاربر بگوید:

سلام

Bot پاسخ می‌دهد:

شما گفتید: سلام

ساخت یک Bot کامل‌تر

اکنون کد ما می‌تواند به شکل زیر باشد:

require("dotenv").config();

const { Telegraf } = require("telegraf");

const bot = new Telegraf(process.env.BOT_TOKEN);

bot.start((ctx) => {
    const name = ctx.from.first_name || "دوست من";

    ctx.reply(
        `سلام ${name}! 👋\n` +
        "به ربات ما خوش آمدید."
    );
});

bot.command("help", (ctx) => {
    ctx.reply(
        "راهنمای ربات:\n\n" +
        "/start - شروع ربات\n" +
        "/help - نمایش راهنما\n" +
        "/about - درباره ربات"
    );
});

bot.command("about", (ctx) => {
    ctx.reply(
        "این Bot با Node.js و Telegraf ساخته شده است."
    );
});

bot.on("text", (ctx) => {
    ctx.reply(`پیام شما: ${ctx.message.text}`);
});

bot.launch();

console.log("Telegram bot is running...");

این نسخه برای شروع کاملاً مناسب است.

دریافت اطلاعات کاربر

یکی از مزایای Context این است که اطلاعات مربوط به کاربر در اختیار ما قرار می‌گیرد.

مثلاً:

bot.start((ctx) => {
    const user = ctx.from;

    console.log(user);
});

می‌توانیم اطلاعاتی مانند موارد زیر را بررسی کنیم:

ctx.from.id
ctx.from.first_name
ctx.from.last_name
ctx.from.username

برای مثال:

bot.start((ctx) => {
    const firstName = ctx.from.first_name;

    ctx.reply(
        `سلام ${firstName}! 👋`
    );
});

ساخت Reply Keyboard

یکی از امکانات جذاب Telegram Botها استفاده از Keyboard است.

برای مثال می‌توانیم یک منوی ساده بسازیم:

const { Markup } = require("telegraf");

bot.start((ctx) => {
    ctx.reply(
        "یکی از گزینه‌ها را انتخاب کنید:",
        Markup.keyboard([
            ["📚 آموزش‌ها"],
            ["ℹ️ درباره ما", "📞 تماس با ما"]
        ])
        .resize()
    );
});

کاربر یک Keyboard شبیه این دریافت می‌کند:

┌─────────────────┐
│   📚 آموزش‌ها   │
├─────────┬───────┤
│ℹ️ درباره ما│📞 تماس│
└─────────┴───────┘

پاسخ به دکمه‌های Keyboard

حالا باید رفتار Bot را هنگام انتخاب گزینه‌ها مشخص کنیم.

bot.hears("📚 آموزش‌ها", (ctx) => {
    ctx.reply("لیست آموزش‌ها در این قسمت نمایش داده می‌شود.");
});

bot.hears("ℹ️ درباره ما", (ctx) => {
    ctx.reply("این بخش درباره پروژه ماست.");
});

bot.hears("📞 تماس با ما", (ctx) => {
    ctx.reply("ایمیل ما: example@example.com");
});

bot.hears() برای زمانی بسیار مفید است که می‌خواهیم به متن خاصی پاسخ دهیم.

Inline Keyboard چیست؟

Inline Keyboard با Reply Keyboard متفاوت است.

در Inline Keyboard دکمه‌ها معمولاً زیر یک پیام قرار می‌گیرند.

برای مثال:

bot.command("menu", (ctx) => {
    ctx.reply(
        "منوی اصلی:",
        Markup.inlineKeyboard([
            [
                Markup.button.callback(
                    "📚 آموزش‌ها",
                    "courses"
                )
            ],
            [
                Markup.button.callback(
                    "ℹ️ درباره ما",
                    "about"
                )
            ]
        ])
    );
});

اکنون دو دکمه زیر پیام قرار می‌گیرند.

مدیریت Callback Query

برای پاسخ به دکمه‌های Inline Keyboard می‌توانیم از action() استفاده کنیم:

bot.action("courses", async (ctx) => {
    await ctx.answerCbQuery();

    await ctx.reply(
        "لیست آموزش‌ها اینجا قرار می‌گیرد."
    );
});

و:

bot.action("about", async (ctx) => {
    await ctx.answerCbQuery();

    await ctx.reply(
        "این پروژه با Node.js و Telegraf ساخته شده است."
    );
});

answerCbQuery() برای پاسخ به Callback Query استفاده می‌شود و باعث می‌شود وضعیت Loading مربوط به کلیک روی دکمه در Telegram مدیریت شود.

یک مثال واقعی‌تر: منوی اصلی Bot

می‌توانیم تمام این قابلیت‌ها را در یک Bot ترکیب کنیم:

require("dotenv").config();

const { Telegraf, Markup } = require("telegraf");

const bot = new Telegraf(process.env.BOT_TOKEN);

bot.start((ctx) => {
    const name = ctx.from.first_name || "دوست من";

    ctx.reply(
        `سلام ${name}! 👋\n\n` +
        "به منوی اصلی خوش آمدید.",
        Markup.inlineKeyboard([
            [
                Markup.button.callback(
                    "📚 آموزش‌ها",
                    "courses"
                )
            ],
            [
                Markup.button.callback(
                    "ℹ️ درباره ما",
                    "about"
                ),
                Markup.button.callback(
                    "📞 تماس",
                    "contact"
                )
            ]
        ])
    );
});

bot.action("courses", async (ctx) => {
    await ctx.answerCbQuery();

    await ctx.reply(
        "📚 آموزش‌های موجود:\n\n" +
        "1. Node.js\n" +
        "2. JavaScript\n" +
        "3. Telegram Bot"
    );
});

bot.action("about", async (ctx) => {
    await ctx.answerCbQuery();

    await ctx.reply(
        "این Bot با Node.js و Telegraf ساخته شده است."
    );
});

bot.action("contact", async (ctx) => {
    await ctx.answerCbQuery();

    await ctx.reply(
        "📧 contact@example.com"
    );
});

bot.launch();

console.log("Bot is running...");

این نمونه از نظر معماری هنوز یک پروژه کوچک است، اما پایه خوبی برای ساخت Botهای واقعی محسوب می‌شود.

Middleware در Telegraf چیست؟

یکی از مفاهیم مهم Telegraf، Middleware است.

فرض کنید می‌خواهیم قبل از اجرای Handlerهای اصلی، یک عملیات انجام دهیم.

مثلاً Logging:

bot.use(async (ctx, next) => {
    console.log(
        "User:",
        ctx.from?.id
    );

    await next();
});

در اینجا هر Update ابتدا وارد Middleware می‌شود.

سپس:

await next();

باعث می‌شود جریان پردازش به Middleware یا Handler بعدی منتقل شود.

معماری کلی:

Telegram Update
      ↓
Middleware
      ↓
Authentication
      ↓
Logging
      ↓
Command Handler
      ↓
Business Logic

Middleware یکی از دلایلی است که Telegraf برای پروژه‌های بزرگ‌تر نیز می‌تواند گزینه مناسبی باشد.

مدیریت خطا در Telegraf

در یک برنامه واقعی باید Error Handling داشته باشیم.

برای مثال:

bot.catch((err, ctx) => {
    console.error(
        "Error while handling update",
        ctx.update,
        err
    );
});

این کار به ما کمک می‌کند خطاهای Runtime را بهتر مشاهده کنیم.

همچنین بهتر است در Production از یک سیستم Logging و Monitoring مناسب استفاده شود.

توقف صحیح Bot

در محیط Production بهتر است Shutdown برنامه را نیز مدیریت کنیم:

process.once("SIGINT", () => bot.stop("SIGINT"));
process.once("SIGTERM", () => bot.stop("SIGTERM"));

این موضوع مخصوصاً در Docker، Kubernetes و سایر محیط‌های Server مهم است.

Polling چیست؟

در مثال‌های بالا از:

bot.launch();

استفاده کردیم.

برای توسعه ساده، Bot می‌تواند Updateهای Telegram را از طریق Long Polling دریافت کند.

مدل کلی:

Telegram
   ↓
Bot API
   ↓
Long Polling
   ↓
Node.js
   ↓
Telegraf
   ↓
Your Handlers

این روش برای Development بسیار ساده است.

Webhook چیست؟

در محیط Production ممکن است بخواهید از Webhook استفاده کنید.

در این مدل، Telegram Update را به URL مشخصی روی سرور شما ارسال می‌کند:

Telegram
    │
    │ HTTPS POST
    ▼
https://example.com/telegram
    │
    ▼
Node.js + Telegraf

Webhook معمولاً زمانی جذاب‌تر است که Bot روی یک سرور دائمی با HTTPS اجرا می‌شود.

تفاوت Polling و Webhook

برای اولین پروژه پیشنهاد من این است:

ابتدا با Polling شروع کنید و بعد از کامل شدن Bot، در صورت نیاز آن را به Webhook منتقل کنید.

اتصال Bot به Database

یک Bot واقعی معمولاً نیاز دارد اطلاعات کاربران را ذخیره کند.

برای مثال:

users
----------------------
id
telegram_id
username
first_name
created_at

وقتی کاربر /start می‌زند:

Telegram
   ↓
Telegraf
   ↓
/start Handler
   ↓
Check User
   ↓
Database
   ↓
Create / Update User

می‌توانید از دیتابیس‌هایی مانند:

• PostgreSQL
• MySQL
• MongoDB
• SQLite

استفاده کنید.

برای پروژه‌های جدی‌تر، PostgreSQL انتخاب بسیار خوبی است؛ مخصوصاً زمانی که داده‌ها رابطه‌ای هستند.

ساختار پیشنهادی پروژه حرفه‌ای

وقتی پروژه بزرگ‌تر شود، بهتر است همه چیز را داخل bot.js قرار ندهیم.

یک ساختار مناسب می‌تواند این باشد:

telegram-bot/
│
├── src/
│   ├── bot.js
│   │
│   ├── handlers/
│   │   ├── start.js
│   │   ├── help.js
│   │   ├── messages.js
│   │   └── callbacks.js
│   │
│   ├── services/
│   │   ├── user.service.js
│   │   └── telegram.service.js
│   │
│   ├── database/
│   │   └── database.js
│   │
│   ├── middleware/
│   │   ├── auth.js
│   │   └── logger.js
│   │
│   └── config/
│       └── config.js
│
├── .env
├── .gitignore
├── package.json
└── package-lock.json

این ساختار باعث می‌شود:

Telegram Layer
      ↓
Handlers
      ↓
Services
      ↓
Database

از یکدیگر جدا باشند.

چه زمانی Telegraf انتخاب خوبی است؟

اگر پروژه شما یک Bot معمولی Node.js است، Telegraf گزینه بسیار مناسبی است.

برای مثال:

Bot پشتیبانی

User
 ↓
Telegram Bot
 ↓
Support System
 ↓
Admin

Bot فروشگاهی

Telegram
 ↓
Products
 ↓
Cart
 ↓
Payment
 ↓
Database

Bot هوش مصنوعی

Telegram
 ↓
Telegraf
 ↓
Node.js
 ↓
AI API
 ↓
Node.js
 ↓
Telegram

Bot اطلاع‌رسانی

Database
 ↓
Node.js
 ↓
Telegraf
 ↓
Telegram Users

اتصال Bot به API خارجی

یکی از مزیت‌های Node.js این است که به راحتی می‌توانیم Bot را به APIهای دیگر متصل کنیم.

مثلاً:

const response = await fetch(
    "https://api.example.com/data"
);

const data = await response.json();

await ctx.reply(
    `Result: ${data.result}`
);

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

اتصال Telegram Bot به هوش مصنوعی

یکی از پروژه‌های محبوب امروزی ساخت AI Telegram Bot است.

معماری کلی:

User
 ↓
Telegram
 ↓
Telegraf
 ↓
Node.js
 ↓
AI API
 ↓
Node.js
 ↓
Telegraf
 ↓
Telegram
 ↓
User

کاربر سؤال خود را ارسال می‌کند.

Telegraf پیام را دریافت می‌کند.

Node.js درخواست را به AI API ارسال می‌کند.

سپس پاسخ دریافت‌شده به Telegram برگردانده می‌شود.

این معماری را می‌توان بعداً با Database، Authentication، Rate Limiting و سیستم پرداخت ترکیب کرد.

نکات امنیتی مهم

Token را Hard-code نکنید

بد:

const bot = new Telegraf(
    "123456789:REAL_TOKEN"
);

خوب:

const bot = new Telegraf(
    process.env.BOT_TOKEN
);

کاربران را به Telegram ID شناسایی کنید

اگر قرار است سیستم احراز هویت یا Permission داشته باشید، معمولاً بهتر است از Telegram User ID به عنوان شناسه اصلی Telegram استفاده کنید.

مثلاً:

const userId = ctx.from.id;

سپس می‌توانید در Database ذخیره کنید:

telegram_id = 123456789

Rate Limiting

اگر Bot عمومی باشد، ممکن است یک کاربر تعداد بسیار زیادی Request ارسال کند.

برای APIهای گران‌قیمت یا عملیات حساس، Rate Limiting اهمیت زیادی دارد.

برای مثال:

User
 ↓
Rate Limiter
 ↓
Handler
 ↓
External API

این موضوع مخصوصاً برای Botهایی که به AI API یا سرویس‌های دارای هزینه متصل هستند اهمیت دارد.

اجرای Bot روی VPS

پس از تکمیل پروژه، می‌توانید آن را روی VPS اجرا کنید.

فرآیند کلی:

Local Development
       ↓
Git
       ↓
VPS
       ↓
Node.js
       ↓
Telegraf
       ↓
Telegram

اما اجرای ساده:

node bot.js

برای Production همیشه ایده‌آل نیست.

اگر Terminal بسته شود یا Process متوقف شود، Bot نیز متوقف می‌شود.

برای مدیریت Process می‌توانید از ابزارهایی مانند PM2 استفاده کنید.

برای مثال:

npm install -g pm2

سپس:

pm2 start bot.js --name telegram-bot

و بررسی وضعیت:

pm2 status

استفاده از Docker

برای پروژه‌های حرفه‌ای‌تر می‌توانید Bot را داخل Docker قرار دهید.

ساختار:

Docker
   ↓
Node.js
   ↓
Telegraf
   ↓
Telegram Bot

یک Dockerfile ساده می‌تواند شبیه این باشد:

FROM node:22-alpine

WORKDIR /app

COPY package*.json ./

RUN npm ci --omit=dev

COPY . .

CMD ["node", "bot.js"]

سپس می‌توانید Image را Build کنید:

docker build -t telegram-bot .

و اجرا کنید:

docker run --env-file .env telegram-bot

برای Production باید تنظیمات امنیتی، Logging، Restart Policy و مدیریت Secretها را نیز در نظر بگیرید.

خطاهای رایج هنگام ساخت Bot با Telegraf

خطای اول: Token اشتباه

اگر Token اشتباه باشد، Bot نمی‌تواند به Telegram متصل شود.

بررسی کنید:

BOT_TOKEN=...

درست باشد.

خطای دوم: .env خوانده نمی‌شود

مطمئن شوید:

require("dotenv").config();

قبل از استفاده از:

process.env.BOT_TOKEN

قرار گرفته است.

خطای سوم: Bot اجرا می‌شود اما پاسخ نمی‌دهد

موارد زیر را بررسی کنید:

1. Bot Token درست است.
2. Bot در Telegram فعال شده است.
3. /start را ارسال کرده‌اید.
4. Process Node.js هنوز فعال است.
5. Errorهای Terminal را بررسی کرده‌اید.
6. Handler مربوطه درست نوشته شده است.

نسخه نهایی پیشنهادی برای شروع

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

require("dotenv").config();

const {
    Telegraf,
    Markup
} = require("telegraf");

const token = process.env.BOT_TOKEN;

if (!token) {
    throw new Error(
        "BOT_TOKEN is not defined in .env"
    );
}

const bot = new Telegraf(token);

bot.start((ctx) => {
    const name =
        ctx.from?.first_name || "دوست من";

    ctx.reply(
        `سلام ${name}! 👋\n\n` +
        "به ربات ما خوش آمدید.",
        Markup.inlineKeyboard([
            [
                Markup.button.callback(
                    "📚 آموزش‌ها",
                    "courses"
                )
            ],
            [
                Markup.button.callback(
                    "ℹ️ درباره ما",
                    "about"
                )
            ]
        ])
    );
});

bot.command("help", (ctx) => {
    ctx.reply(
        "دستورات موجود:\n\n" +
        "/start - شروع ربات\n" +
        "/help - راهنما"
    );
});

bot.action("courses", async (ctx) => {
    await ctx.answerCbQuery();

    await ctx.reply(
        "📚 آموزش‌های موجود:\n\n" +
        "• Node.js\n" +
        "• JavaScript\n" +
        "• Telegram Bot\n" +
        "• Telegraf"
    );
});

bot.action("about", async (ctx) => {
    await ctx.answerCbQuery();

    await ctx.reply(
        "این Telegram Bot با Node.js و Telegraf ساخته شده است."
    );
});

bot.on("text", (ctx) => {
    ctx.reply(
        `پیام شما دریافت شد:\n${ctx.message.text}`
    );
});

bot.catch((error, ctx) => {
    console.error(
        "Error while processing update:",
        error
    );
});

bot.launch();

process.once("SIGINT", () => {
    bot.stop("SIGINT");
});

process.once("SIGTERM", () => {
    bot.stop("SIGTERM");
});

console.log(
    "Telegram Bot is running..."
);

جمع‌بندی

در این آموزش یاد گرفتیم چگونه یک Telegram Bot با Node.js و Telegraf بسازیم.

مسیر کلی به این شکل بود:

BotFather
   ↓
Bot Token
   ↓
Node.js Project
   ↓
Install Telegraf
   ↓
.env
   ↓
Telegraf Bot
   ↓
Commands
   ↓
Messages
   ↓
Keyboard
   ↓
Inline Keyboard
   ↓
Middleware
   ↓
Database / API
   ↓
Production

مهم‌ترین بخش این پروژه این است که ساخت یک Bot ساده بسیار آسان است، اما معماری آن زمانی اهمیت پیدا می‌کند که Bot شروع به مدیریت کاربران، دیتابیس، APIهای خارجی، پرداخت یا سرویس‌های هوش مصنوعی کند.

برای یک پروژه کوچک، یک فایل bot.js کافی است؛ اما برای یک Bot حرفه‌ای بهتر است از همان ابتدا Handlers، Services، Middleware و Database Layer را از هم جدا کنیم.

سوالات متداول درباره Telegraf و Node.js

Telegraf چیست؟

Telegraf یک Framework برای ساخت Telegram Bot با JavaScript و TypeScript است.

آیا Telegraf با Node.js کار می‌کند؟

بله. Telegraf برای ساخت Botهای Telegram در محیط Node.js قابل استفاده است.

آیا برای ساخت Telegram Bot باید JavaScript بلد باشم؟

برای ساخت Bot با Node.js و Telegraf، دانستن JavaScript بسیار کمک‌کننده است. برای شروع به دانش پیشرفته JavaScript نیاز ندارید، اما برای پروژه‌های حرفه‌ای باید مفاهیمی مانند Async/Await، Promise، Error Handling و Moduleها را بدانید.

Telegraf بهتر است یا grammY؟

هر دو گزینه‌های مناسبی برای توسعه Telegram Bot با JavaScript/TypeScript هستند. انتخاب بین آن‌ها بیشتر به API، اکوسیستم، تجربه توسعه‌دهنده و معماری پروژه شما بستگی دارد.

اگر با Telegraf شروع کرده‌اید، دلیلی وجود ندارد صرفاً به خاطر استفاده از grammY پروژه خود را تغییر دهید؛ مهم‌تر از نام Framework، معماری صحیح Bot است.

آیا می‌توان با Telegraf ربات فروشگاهی ساخت؟

بله. Telegraf می‌تواند لایه Telegram پروژه باشد و می‌توان آن را به Database، سیستم پرداخت، API محصولات و Backend متصل کرد.

آیا می‌توان Telegraf را به OpenAI یا سایر AI APIها متصل کرد؟

بله. Node.js می‌تواند درخواست را از Telegram دریافت کرده، آن را به یک AI API ارسال کند و پاسخ را مجدداً از طریق Telegraf به کاربر ارسال کند.

آیا می‌توان Bot ساخته‌شده با Telegraf را روی VPS اجرا کرد؟

بله. می‌توانید Bot را روی VPS اجرا کنید و برای مدیریت Process از ابزارهایی مانند PM2 یا Docker استفاده کنید.

نتیجه نهایی

اگر هدف شما یادگیری ساخت ربات تلگرام با Node.js است، ترکیب Node.js و Telegraf نقطه شروع بسیار خوبی است.

با چند خط کد می‌توانید یک Bot ساده بسازید و سپس به تدریج قابلیت‌های حرفه‌ای مانند:

Database
Authentication
Admin Panel
Payments
AI
Webhooks
Docker
REST API
Rate Limiting
Logging

را به آن اضافه کنید.

بهترین مسیر یادگیری این است که بعد از ساخت Bot ساده، یک پروژه واقعی کوچک ایجاد کنید؛ برای مثال ربات مدیریت وظایف، ربات پشتیبانی، ربات فروشگاهی یا AI Telegram Bot. این کار مفاهیمی مانند Middleware، Database و معماری Backend را بسیار بهتر از مثال‌های مستقل به شما آموزش می‌دهد.