Tutorial 11 min read

Building a Telegram Bot with Node.js — Zero to Production

Mahmoud Hamdy

March 18, 2026

Telegram bots are one of the most developer-friendly automation tools available today. No approval process, no template reviews, no per-conversation fees. You create a bot in seconds through @BotFather, write your Node.js code, and you are live. I have built over a dozen Telegram bots — notification systems for e-commerce stores, admin panels for internal operations, customer-facing support bots — and the pattern is always the same: fast to build, easy to deploy, and incredibly reliable. This tutorial takes you from zero to a deployed production bot.

Why Telegram for Bots?

Telegram's bot API is free, has no rate limits on incoming messages (only outgoing: 30 messages/second per bot), supports rich media out of the box, and has 900 million monthly active users as of 2026. In the MENA region, Telegram has surged in popularity — particularly in Egypt, Saudi Arabia, and the UAE — making it a natural choice for customer-facing automation. The API is also significantly more developer-friendly than WhatsApp's: no approval needed, no templates required, and you can test locally without a public HTTPS endpoint (long polling works in development).

BotFather Setup

Creating a bot takes two minutes. Open Telegram, search for @BotFather, and send /newbot. You will be prompted for a name and a username (must end in "bot"). BotFather instantly returns your bot token — a string like 7234567890:AAHdqTcvCH1vGWJxfSeofSh0riPEiYZ5-OY. Store this in your .env file as TELEGRAM_BOT_TOKEN and never commit it to version control.

# .env
TELEGRAM_BOT_TOKEN=7234567890:AAHdqTcvCH1vGWJxfSeofSh0riPEiYZ5-OY
NODE_ENV=development

Project Setup with Telegraf

telegraf is the de-facto standard Node.js library for Telegram bots. It is well-maintained, TypeScript-native, and supports all Telegram Bot API features including scenes, sessions, and middleware. Install it alongside TypeScript:

npm init -y
npm install telegraf dotenv
npm install -D typescript ts-node @types/node nodemon
npx tsc --init

// src/index.ts
import { Telegraf } from 'telegraf';
import * as dotenv from 'dotenv';
dotenv.config();

const bot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN!);

bot.start(ctx => ctx.reply('Welcome! Send /help to see what I can do.'));
bot.help(ctx => ctx.reply('Commands:\n/start — Introduction\n/status — Bot status\n/menu — Main menu'));

bot.launch();
console.log('Bot is running...');

// Graceful shutdown
process.once('SIGINT', () => bot.stop('SIGINT'));
process.once('SIGTERM', () => bot.stop('SIGTERM'));

Registering Commands

Registering commands in @BotFather (via /setcommands) enables the blue "/" autocomplete menu in Telegram's interface. Your bot should register the same commands programmatically via the API for consistency:

// src/commands.ts
import { Telegraf } from 'telegraf';

export function registerCommands(bot: Telegraf) {
  bot.command('start', async ctx => {
    const name = ctx.from.first_name;
    await ctx.reply(
      `Hello ${name}! I am your store assistant.\n\n` +
      `Use /track to check an order\n` +
      `Use /menu for all options\n` +
      `Use /help if you need assistance`
    );
  });

  bot.command('status', async ctx => {
    await ctx.reply('All systems operational. Response time: < 1s.');
  });

  // Handle plain text (non-command) messages
  bot.on('text', async ctx => {
    const text = ctx.message.text.toLowerCase();
    if (text.includes('order') || text.includes('طلب')) {
      await ctx.reply('To track your order, please send /track followed by your order number.');
    } else {
      await ctx.reply('I did not understand that. Send /help for available commands.');
    }
  });
}

Inline Keyboards and Callbacks

Inline keyboards are buttons attached to a specific message. They are the most powerful UX tool in the Telegram bot toolkit. When a user taps a button, Telegram sends a callback_query event with the button's data string. You handle it with bot.action():

// src/menus.ts
import { Markup } from 'telegraf';

export function mainMenuKeyboard() {
  return Markup.inlineKeyboard([
    [
      Markup.button.callback('Track Order', 'track_order'),
      Markup.button.callback('My Orders', 'my_orders'),
    ],
    [
      Markup.button.callback('Browse Products', 'browse_products'),
      Markup.button.callback('Contact Support', 'contact_support'),
    ],
  ]);
}

export function registerCallbacks(bot: Telegraf) {
  bot.command('menu', async ctx => {
    await ctx.reply('What would you like to do?', mainMenuKeyboard());
  });

  bot.action('track_order', async ctx => {
    await ctx.answerCbQuery(); // Remove "loading" spinner
    await ctx.reply('Please enter your order reference number (e.g. ORD-1234):');
    // Set session state — handled in next message
  });

  bot.action('contact_support', async ctx => {
    await ctx.answerCbQuery();
    await ctx.reply(
      'Our support team is available 9AM–9PM (AST).\n' +
      'You can also email us at support@store.com',
      Markup.inlineKeyboard([
        [Markup.button.url('Send Email', 'mailto:support@store.com')],
        [Markup.button.callback('Back to Menu', 'main_menu')],
      ])
    );
  });

  bot.action('main_menu', async ctx => {
    await ctx.answerCbQuery();
    await ctx.editMessageReplyMarkup(mainMenuKeyboard().reply_markup);
  });
}

Session State with Telegraf Scenes

For multi-step conversations (like an order tracking flow that asks for an order number then shows the result), Telegraf's scene system is the cleanest approach. A scene is a self-contained conversation state that captures user input across multiple messages:

// src/scenes/track-order.ts
import { Scenes, Markup } from 'telegraf';
import { SallaClient } from '../salla/client';

export const trackOrderScene = new Scenes.WizardScene(
  'TRACK_ORDER',

  // Step 1: Ask for order number
  async ctx => {
    await ctx.reply('Enter your order number:');
    return ctx.wizard.next();
  },

  // Step 2: Fetch and display order
  async ctx => {
    if (!ctx.message || !('text' in ctx.message)) {
      await ctx.reply('Please enter a text order number.');
      return;
    }
    const orderId = ctx.message.text.trim();
    try {
      const salla = new SallaClient(process.env.SALLA_TOKEN!);
      const order = await salla.getOrderByReference(orderId);
      await ctx.reply(
        `Order #${order.reference_id}\n` +
        `Status: ${order.status.name}\n` +
        `Total: ${order.amounts.total.amount} SAR\n` +
        `Placed: ${new Date(order.date.date).toLocaleDateString('en-SA')}`
      );
    } catch {
      await ctx.reply('Order not found. Double-check the number and try again.');
    }
    return ctx.scene.leave();
  }
);

// Register in bot setup:
// const stage = new Scenes.Stage([trackOrderScene]);
// bot.use(session());
// bot.use(stage.middleware());

Integrating External APIs

Telegram bots become genuinely powerful when connected to external data sources. I have used this pattern to connect bots to Salla order APIs, weather services, database queries, and internal admin APIs. The key principle is to always handle API errors gracefully — if an external call fails, the bot should send a meaningful message, not crash silently:

// src/lib/safe-api-call.ts
export async function safeApiCall(
  fn: () => Promise,
  fallbackMessage: string
): Promise {
  try {
    return await fn();
  } catch (error) {
    console.error('[API Error]', error instanceof Error ? error.message : error);
    return null;
  }
}

// Usage in a command handler:
bot.command('stats', async ctx => {
  const stats = await safeApiCall(
    () => analyticsClient.getDailyStats(),
    'Could not load stats right now.'
  );

  if (!stats) {
    await ctx.reply('Stats are unavailable at the moment. Try again in a minute.');
    return;
  }

  await ctx.reply(
    `Today's stats:\n` +
    `Orders: ${stats.orderCount}\n` +
    `Revenue: SAR ${stats.revenue.toFixed(2)}\n` +
    `New customers: ${stats.newCustomers}`
  );
});

Webhook vs. Long Polling

Telegraf supports two modes. Long polling (bot.launch()) works out of the box for local development — the bot polls Telegram's servers for new updates every few seconds. It requires no public URL and is perfect for development. For production, webhooks are better: Telegram pushes updates to your server instantly, there is no polling overhead, and the bot is more responsive. Switch with one config change:

// src/index.ts
if (process.env.NODE_ENV === 'production') {
  const WEBHOOK_URL = process.env.WEBHOOK_URL!; // e.g. https://yourdomain.com/webhook
  bot.launch({
    webhook: {
      domain: WEBHOOK_URL,
      port: parseInt(process.env.PORT ?? '3000'),
    },
  });
} else {
  bot.launch(); // Long polling for local dev
}

Building a Store Notification Bot

This is the practical end-goal I build most often: a bot that notifies a merchant's Telegram channel every time a new order comes in from their Salla store. The bot runs alongside the webhook server. When a new order is received, it formats a rich message with order details and sends it to the merchant's private group or channel:

// src/notifications/store-alerts.ts
import { Telegraf } from 'telegraf';
import type { SallaOrder } from '../salla/types';

const ALERT_CHANNEL_ID = process.env.TELEGRAM_ALERT_CHANNEL!;

export async function sendNewOrderAlert(bot: Telegraf, order: SallaOrder): Promise {
  const itemLines = order.items
    .map(item => `  • ${item.name} × ${item.quantity} — SAR ${item.total}`)
    .join('\n');

  const message =
    `New Order Received\n\n` +
    `Order: #${order.reference_id}\n` +
    `Customer: ${order.customer.first_name} ${order.customer.last_name}\n` +
    `Phone: ${order.customer.mobile ?? 'N/A'}\n` +
    `Total: SAR ${order.amounts.total.amount}\n\n` +
    `Items:\n${itemLines}\n\n` +
    `Payment: ${order.payment_method}\n` +
    `Placed: ${new Date(order.date.date).toLocaleString('en-SA', { timeZone: 'Asia/Riyadh' })}`;

  await bot.telegram.sendMessage(ALERT_CHANNEL_ID, message, {
    parse_mode: 'HTML',
  });
}

Error Handling and Reliability

Telegram bots in production face two reliability challenges: Telegram API timeouts (rare but they happen) and unhandled promise rejections that crash the process. Telegraf has a built-in error handler:

bot.catch((err, ctx) => {
  console.error(`[Bot Error] User: ${ctx.from?.id}`, err);
  // Only reply if we are not already in an error handler to avoid loops
  ctx.reply('An error occurred. Please try again.').catch(() => {});
});

For deployment, I always use PM2 with --max-restarts 10 and a --restart-delay 3000. This handles transient errors without hammering the server. Log the restart events to catch patterns — if a bot restarts 10 times in an hour, something structural is wrong and needs investigation.

Deploying to a VPS

The full deployment on a fresh Ubuntu 22.04 VPS takes about 15 minutes:

# On the server
# 1. Install Node.js 20 via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc && nvm install 20

# 2. Clone your project
git clone https://github.com/yourname/telegram-bot.git && cd telegram-bot
npm install && npm run build

# 3. Create .env with production values
cp .env.example .env && nano .env

# 4. Install PM2 and start
npm install -g pm2
pm2 start dist/index.js --name telegram-bot
pm2 save && pm2 startup

# 5. If using webhooks — set up Nginx + Certbot for HTTPS
sudo apt install nginx certbot python3-certbot-nginx -y
sudo certbot --nginx -d yourdomain.com

بوتات تيليجرام هي من أكثر أدوات الأتمتة سهولةً للمطورين اليوم. لا يوجد عملية موافقة، ولا مراجعة قوالب، ولا رسوم لكل محادثة. تنشئ بوتًا في ثوانٍ عبر @BotFather، وتكتب كود Node.js، وتكون جاهزًا. لقد بنيت أكثر من اثني عشر بوت تيليجرام — أنظمة إشعار لمتاجر إلكترونية، ولوحات إدارية للعمليات الداخلية، وبوتات دعم موجهة للعملاء — والنمط دائمًا نفسه: سريع البناء، سهل النشر، وموثوقية عالية. هذا الدليل يأخذك من الصفر إلى بوت إنتاجي منشور فعلًا.

لماذا تيليجرام للبوتات؟

تيليجرام Bot API مجاني، وليس له حدود معدل على الرسائل الواردة (فقط الصادرة: 30 رسالة/ثانية لكل بوت)، ويدعم الوسائط الغنية من الصندوق. في منطقة الشرق الأوسط وشمال أفريقيا، شهد تيليجرام طفرة كبيرة — لا سيما في مصر والسعودية والإمارات — مما يجعله خيارًا طبيعيًا للأتمتة الموجهة للعملاء. الـ API أيضًا أكثر مرونة للمطورين من واتساب: لا موافقة مطلوبة، ولا قوالب إلزامية، ويمكنك الاختبار محليًا بدون عنوان HTTPS عام (Long Polling يعمل في التطوير).

إعداد BotFather

إنشاء بوت يستغرق دقيقتين. افتح تيليجرام وابحث عن @BotFather وأرسل /newbot. ستُطلب منك الاسم ثم اسم المستخدم (يجب أن ينتهي بـ "bot"). يعود BotFather فورًا بتوكن البوت — سلسلة مثل 7234567890:AAHdqTcvCH1vGWJxfSeofSh0riPEiYZ5-OY. خزّنه في ملف .env باسم TELEGRAM_BOT_TOKEN ولا ترفعه أبدًا إلى أي مستودع.

إعداد المشروع مع Telegraf

telegraf هو المكتبة القياسية de-facto لبوتات تيليجرام في Node.js. محافظ عليها جيدًا، دعم TypeScript أصلي، وتدعم جميع ميزات Telegram Bot API بما في ذلك الـ Scenes والـ Sessions والـ Middleware. قم بتثبيتها:

npm install telegraf dotenv
npm install -D typescript ts-node @types/node nodemon

// src/index.ts
import { Telegraf } from 'telegraf';
import * as dotenv from 'dotenv';
dotenv.config();

const bot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN!);

bot.start(ctx => ctx.reply('أهلًا! أرسل /help لترى ما أستطيع فعله.'));
bot.help(ctx => ctx.reply('الأوامر:\n/start — مقدمة\n/status — حالة البوت\n/menu — القائمة الرئيسية'));

bot.launch();
console.log('البوت يعمل...');

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

تسجيل الأوامر

تسجيل الأوامر في @BotFather يتيح قائمة الإكمال التلقائي للرمز "/" في واجهة تيليجرام. بوتك يجب أن يتعامل مع نفس الأوامر برمجيًا:

// src/commands.ts
export function registerCommands(bot: Telegraf) {
  bot.command('start', async ctx => {
    const name = ctx.from.first_name;
    await ctx.reply(
      `مرحبًا ${name}! أنا مساعد متجرك.\n\n` +
      `/track — تتبع طلب\n` +
      `/menu — جميع الخيارات\n` +
      `/help — المساعدة`
    );
  });

  // التعامل مع الرسائل النصية العادية
  bot.on('text', async ctx => {
    const text = ctx.message.text.toLowerCase();
    if (text.includes('order') || text.includes('طلب')) {
      await ctx.reply('لتتبع طلبك، أرسل /track متبوعًا برقم الطلب.');
    } else {
      await ctx.reply('لم أفهم ذلك. أرسل /help للأوامر المتاحة.');
    }
  });
}

لوحات المفاتيح المضمنة والـ Callbacks

لوحات المفاتيح المضمنة (Inline Keyboards) هي أزرار مرفقة برسالة بعينها. وهي أقوى أداة UX في ترسانة بوتات تيليجرام. عندما يضغط المستخدم على زر، يرسل تيليجرام حدث callback_query مع سلسلة بيانات الزر. تتعامل معه عبر bot.action():

// src/menus.ts
import { Markup } from 'telegraf';

export function mainMenuKeyboard() {
  return Markup.inlineKeyboard([
    [
      Markup.button.callback('تتبع طلب', 'track_order'),
      Markup.button.callback('طلباتي', 'my_orders'),
    ],
    [
      Markup.button.callback('تصفح المنتجات', 'browse_products'),
      Markup.button.callback('التواصل مع الدعم', 'contact_support'),
    ],
  ]);
}

export function registerCallbacks(bot: Telegraf) {
  bot.command('menu', async ctx => {
    await ctx.reply('ماذا تريد أن تفعل؟', mainMenuKeyboard());
  });

  bot.action('track_order', async ctx => {
    await ctx.answerCbQuery();
    await ctx.reply('أدخل رقم مرجع طلبك (مثلًا: ORD-1234):');
  });

  bot.action('contact_support', async ctx => {
    await ctx.answerCbQuery();
    await ctx.reply(
      'فريق الدعم متاح من 9 صباحًا حتى 9 مساءً.\n' +
      'يمكنك أيضًا مراسلتنا على support@store.com',
      Markup.inlineKeyboard([
        [Markup.button.url('إرسال بريد', 'mailto:support@store.com')],
        [Markup.button.callback('العودة للقائمة', 'main_menu')],
      ])
    );
  });
}

إدارة الحالة مع Telegraf Scenes

للمحادثات متعددة الخطوات كتدفق تتبع الطلب الذي يطلب رقمًا ثم يعرض النتيجة، نظام Scenes في Telegraf هو النهج الأنظف. الـ Scene هي حالة محادثة مستقلة تلتقط مدخلات المستخدم عبر رسائل متعددة:

// src/scenes/track-order.ts
import { Scenes } from 'telegraf';

export const trackOrderScene = new Scenes.WizardScene(
  'TRACK_ORDER',

  // الخطوة 1: طلب رقم الطلب
  async ctx => {
    await ctx.reply('أدخل رقم طلبك:');
    return ctx.wizard.next();
  },

  // الخطوة 2: جلب الطلب وعرضه
  async ctx => {
    if (!ctx.message || !('text' in ctx.message)) {
      await ctx.reply('رجاءً أدخل رقمًا نصيًا.');
      return;
    }
    const orderId = ctx.message.text.trim();
    try {
      const salla = new SallaClient(process.env.SALLA_TOKEN!);
      const order = await salla.getOrderByReference(orderId);
      await ctx.reply(
        `طلب #${order.reference_id}\n` +
        `الحالة: ${order.status.name}\n` +
        `الإجمالي: ${order.amounts.total.amount} ريال`
      );
    } catch {
      await ctx.reply('لم يُعثر على الطلب. تحقق من الرقم وأعد المحاولة.');
    }
    return ctx.scene.leave();
  }
);

بناء بوت إشعارات المتجر

هذا هو الهدف العملي الذي أبنيه في أغلب الأحيان: بوت يُشعر قناة تيليجرام الخاصة بالتاجر في كل مرة يرد طلب جديد من متجر سلة. البوت يعمل بجانب خادم الويب هوك. حين يصل طلب جديد، يُنسّق رسالة غنية بتفاصيل الطلب ويرسلها للمجموعة أو القناة الخاصة بالتاجر:

// src/notifications/store-alerts.ts
export async function sendNewOrderAlert(bot: Telegraf, order: SallaOrder): Promise {
  const itemLines = order.items
    .map(item => `  • ${item.name} × ${item.quantity} — ${item.total} ريال`)
    .join('\n');

  const message =
    `طلب جديد وارد\n\n` +
    `الطلب: #${order.reference_id}\n` +
    `العميل: ${order.customer.first_name} ${order.customer.last_name}\n` +
    `الجوال: ${order.customer.mobile ?? 'غير متوفر'}\n` +
    `الإجمالي: ${order.amounts.total.amount} ريال\n\n` +
    `المنتجات:\n${itemLines}\n\n` +
    `طريقة الدفع: ${order.payment_method}`;

  await bot.telegram.sendMessage(ALERT_CHANNEL_ID, message, {
    parse_mode: 'HTML',
  });
}

Webhook مقابل Long Polling

Telegraf يدعم وضعين. Long Polling يعمل من الصندوق في التطوير المحلي — البوت يستعلم خوادم تيليجرام عن التحديثات الجديدة كل ثوانٍ قليلة. لا يحتاج عنوانًا عامًا ومثالي للتطوير. في الإنتاج، الويب هوك أفضل: تيليجرام يدفع التحديثات لخادمك فورًا دون أي تأخر.

معالجة الأخطاء والموثوقية

Telegraf لديه معالج أخطاء مدمج. دائمًا استخدمه — لا تتركه للـ Node.js process uncaughtException:

bot.catch((err, ctx) => {
  console.error(`[Bot Error] المستخدم: ${ctx.from?.id}`, err);
  ctx.reply('حدث خطأ. الرجاء المحاولة مرة أخرى.').catch(() => {});
});

للنشر، أستخدم دائمًا PM2 مع --max-restarts 10 و--restart-delay 3000. هذا يتعامل مع الأخطاء العابرة دون إرهاق الخادم. سجّل أحداث إعادة التشغيل لرصد الأنماط — إن أعاد البوت التشغيل 10 مرات في ساعة، فهناك شيء بنيوي يحتاج تحقيقًا.