بناء بوت تيليجرام باستخدام grammY و TypeScript: من الصفر إلى النشر

mkdir telegram-grammy-bot && cd telegram-grammy-bot
npm init -y
npm install grammy dotenv
npm install -D typescript @types/node tsx
npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "skipLibCheck": true
  },
  "include": ["src"]
}

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/bot.ts",
    "build": "tsc",
    "start": "node dist/bot.js"
  }
}

BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

import { Bot } from "grammy";
import "dotenv/config";
 
const token = process.env.BOT_TOKEN;
if (!token) throw new Error("BOT_TOKEN is not set");
 
const bot = new Bot(token);
 
// التعامل مع أمر /start
bot.command("start", (ctx) => {
  ctx.reply(
    `مرحباً ${ctx.from?.first_name}! 👋\nأنا بوت مبني بـ grammY و TypeScript.`
  );
});
 
// التعامل مع أمر /help
bot.command("help", (ctx) => {
  ctx.reply(
    "الأوامر المتاحة:\n" +
    "/start - تشغيل البوت\n" +
    "/help - عرض رسالة المساعدة\n" +
    "/about - معرفة المزيد عن البوت"
  );
});
 
// إعادة إرسال أي رسالة نصية
bot.on("message:text", (ctx) => {
  ctx.reply(`قلت: ${ctx.message.text}`);
});
 
// تشغيل البوت
bot.start();
console.log("البوت يعمل...");

npm run dev

import { InlineKeyboard } from "grammy";
 
export const mainMenu = new InlineKeyboard()
  .text("📊 الحالة", "status")
  .text("⚙️ الإعدادات", "settings")
  .row()
  .text("ℹ️ حول", "about")
  .text("📞 تواصل", "contact");
 
export const settingsMenu = new InlineKeyboard()
  .text("🌍 اللغة", "lang")
  .text("🔔 الإشعارات", "notif")
  .row()
  .text("« العودة للقائمة", "back_to_menu");

import { Bot } from "grammy";
import { mainMenu, settingsMenu } from "./keyboards.js";
import "dotenv/config";
 
const token = process.env.BOT_TOKEN;
if (!token) throw new Error("BOT_TOKEN is not set");
 
const bot = new Bot(token);
 
bot.command("start", (ctx) => {
  ctx.reply("مرحباً! اختر خياراً:", { reply_markup: mainMenu });
});
 
// التعامل مع نقرات الأزرار
bot.callbackQuery("status", (ctx) => {
  ctx.answerCallbackQuery();
  ctx.editMessageText("✅ البوت يعمل بسلاسة!\n\nنسبة التشغيل: 99.9%", {
    reply_markup: new InlineKeyboard().text("« رجوع", "back_to_menu"),
  });
});
 
bot.callbackQuery("settings", (ctx) => {
  ctx.answerCallbackQuery();
  ctx.editMessageText("⚙️ الإعدادات:", { reply_markup: settingsMenu });
});
 
bot.callbackQuery("about", async (ctx) => {
  await ctx.answerCallbackQuery();
  await ctx.editMessageText(
    "هذا البوت مبني بـ grammY + TypeScript.\nالإصدار: 1.0.0",
    { reply_markup: new InlineKeyboard().text("« رجوع", "back_to_menu") }
  );
});
 
bot.callbackQuery("back_to_menu", (ctx) => {
  ctx.answerCallbackQuery();
  ctx.editMessageText("اختر خياراً:", { reply_markup: mainMenu });
});
 
bot.start();

import { Composer } from "grammy";
import type { MyContext } from "../types.js";
 
const admin = new Composer<MyContext>();
 
const ADMIN_IDS = [123456789]; // استبدل بمعرف المستخدم الخاص بك
 
admin.command("broadcast", async (ctx) => {
  if (!ADMIN_IDS.includes(ctx.from?.id ?? 0)) {
    return ctx.reply("⛔ غير مصرح لك باستخدام هذا الأمر.");
  }
  const message = ctx.match;
  if (!message) {
    return ctx.reply("الاستخدام: /broadcast <الرسالة>");
  }
  await ctx.reply(`📢 إذاعة: ${message}`);
});
 
admin.command("stats", async (ctx) => {
  if (!ADMIN_IDS.includes(ctx.from?.id ?? 0)) {
    return ctx.reply("⛔ غير مصرح.");
  }
  await ctx.reply("📊 إحصائيات البوت:\n- المستخدمون: 42\n- الرسائل اليوم: 156");
});
 
export default admin;

import type { Context, SessionFlavor } from "grammy";
 
export interface SessionData {
  language: string;
  notificationsEnabled: boolean;
  messageCount: number;
}
 
export type MyContext = Context & SessionFlavor<SessionData>;

import admin from "./handlers/admin.js";
 
// ... إعداد البوت ...
 
bot.use(admin);

npm install @grammyjs/storage-file

import { Bot, session } from "grammy";
import type { MyContext, SessionData } from "./types.js";
import "dotenv/config";
 
const token = process.env.BOT_TOKEN;
if (!token) throw new Error("BOT_TOKEN is not set");
 
const bot = new Bot<MyContext>(token);
 
function defaultSession(): SessionData {
  return {
    language: "ar",
    notificationsEnabled: true,
    messageCount: 0,
  };
}
 
bot.use(
  session({
    initial: defaultSession,
  })
);
 
// وسيط لعد الرسائل
bot.use(async (ctx, next) => {
  if (ctx.message) {
    ctx.session.messageCount++;
  }
  await next();
});
 
bot.command("mystats", (ctx) => {
  const { language, notificationsEnabled, messageCount } = ctx.session;
  ctx.reply(
    `📊 إحصائياتك:\n` +
    `- اللغة: ${language}\n` +
    `- الإشعارات: ${notificationsEnabled ? "مفعّلة" : "معطّلة"}\n` +
    `- الرسائل المرسلة: ${messageCount}`
  );
});
 
bot.command("setlang", (ctx) => {
  const lang = ctx.match;
  if (!lang || !["en", "ar", "fr"].includes(lang)) {
    return ctx.reply("الاستخدام: /setlang <en|ar|fr>");
  }
  ctx.session.language = lang;
  ctx.reply(`✅ تم تعيين اللغة إلى: ${lang}`);
});
 
bot.start();

npm install @grammyjs/conversations

import type { MyContext } from "../types.js";
import type { Conversation } from "@grammyjs/conversations";
 
type FeedbackConversation = Conversation<MyContext>;
 
export async function feedbackFlow(
  conversation: FeedbackConversation,
  ctx: MyContext
) {
  await ctx.reply("📝 أحب أن أسمع رأيك!\n\nما اسمك؟");
  const nameCtx = await conversation.waitFor("message:text");
  const name = nameCtx.message.text;
 
  await ctx.reply(`شكراً ${name}! كيف تقيّم خدمتنا؟ (1-5)`);
  let rating: number;
 
  do {
    const ratingCtx = await conversation.waitFor("message:text");
    rating = parseInt(ratingCtx.message.text);
    if (isNaN(rating) || rating < 1 || rating > 5) {
      await ctx.reply("الرجاء إدخال رقم بين 1 و 5.");
    }
  } while (isNaN(rating) || rating < 1 || rating > 5);
 
  await ctx.reply("أي تعليقات إضافية؟ (أرسل /skip للتخطي)");
  const commentCtx = await conversation.waitFor("message:text");
  const comment =
    commentCtx.message.text === "/skip" ? "بدون تعليق" : commentCtx.message.text;
 
  await ctx.reply(
    `✅ تم استلام الملاحظات!\n\n` +
    `الاسم: ${name}\n` +
    `التقييم: ${"⭐".repeat(rating)}\n` +
    `التعليق: ${comment}\n\n` +
    `شكراً لملاحظاتك!`
  );
}

import { conversations, createConversation } from "@grammyjs/conversations";
import { feedbackFlow } from "./conversations/feedback.js";
 
// أضف بعد وسيط الجلسات
bot.use(conversations());
bot.use(createConversation(feedbackFlow));
 
bot.command("feedback", async (ctx) => {
  await ctx.conversation.enter("feedbackFlow");
});

import { BotError, GrammyError, HttpError } from "grammy";
 
bot.catch((err: BotError) => {
  const ctx = err.ctx;
  console.error(`خطأ أثناء معالجة التحديث ${ctx.update.update_id}:`);
 
  const e = err.error;
  if (e instanceof GrammyError) {
    console.error("خطأ في الطلب:", e.description);
    if (e.description.includes("message is not modified")) {
      // المستخدم نقر نفس الزر مرتين — آمن للتجاهل
      return;
    }
  } else if (e instanceof HttpError) {
    console.error("تعذر الاتصال بتيليجرام:", e);
  } else {
    console.error("خطأ غير معروف:", e);
  }
});

npm install hono @hono/node-server

import { Bot, webhookCallback } from "grammy";
import { Hono } from "hono";
import { serve } from "@hono/node-server";
import type { MyContext } from "./types.js";
import "dotenv/config";
 
const token = process.env.BOT_TOKEN;
if (!token) throw new Error("BOT_TOKEN is not set");
 
const bot = new Bot<MyContext>(token);
 
// ... سجّل جميع المعالجات والوسيط والجلسات ...
 
bot.command("start", (ctx) => ctx.reply("مرحباً من وضع webhook!"));
 
const app = new Hono();
 
app.get("/", (c) => c.text("البوت يعمل"));
app.post(`/webhook/${token}`, webhookCallback(bot, "hono"));
 
const PORT = parseInt(process.env.PORT || "3000");
 
serve({ fetch: app.fetch, port: PORT }, () => {
  console.log(`خادم Webhook يعمل على المنفذ ${PORT}`);
});
 
// عيّن رابط webhook (شغّل مرة واحدة)
// bot.api.setWebhook(`https://your-domain.com/webhook/${token}`);

curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.com/webhook/<YOUR_TOKEN>"}'

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=builder /app/dist ./dist
COPY .env .env
 
EXPOSE 3000
CMD ["node", "dist/webhook.js"]

docker build -t grammy-bot .
docker run -d --name grammy-bot -p 3000:3000 grammy-bot