کتابخونهٔ python-telegram-bot یکی از محبوب‌ترین ابزارها برای ساخت ربات تلگرام با Python هست. اگر حوصلهٔ کار مستقیم با HTTP و API خام تلگرام رو نداری، این لایبرری خیلی از دردسرها رو جمع می‌کنه 🧩

چند تا مزیت مهم:
• پشتیبانی کامل از Bot API
• پشتیبانی هم از polling هم webhook
• ساخت راحت inline keyboard و reply keyboard
• سیستم handler‌ ها برای مرتب نگه داشتن کد

نمونهٔ سادهٔ ربات /start:

pip install python-telegram-bot==21.6

from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text("سلام، ربات آنلاینه ✌️")

app = ApplicationBuilder().token("BOT_TOKEN").build()
app.add_handler(CommandHandler("start", start))
app.run_polling()

برای پروژه‌های جدی هم ساختن ساختار تمیز با handler ها و استفاده از webhook روی سرور خیلی راحت می‌شه. پیشنهاد می‌شه مستنداتش رو یک بار کامل اسکن کنی و با مثال‌هاش جلو بری 🚀

Docs | GitHub

🔖 #TelegramBot #ربات #تلگرام #python_telegram_bot #Python #Telegram_Bot #ربات_تلگرام #Webhook #Inline_Keyboard

👤 Developix

💎 Channel: @DevelopixRobot

‏Circuit Breaker در ربات‌های تلگرام ⚡️🛡

خیلی وقت‌ها ربات تلگرام ما به یک سرویس خارجی (مثلاً پرداخت، هوش مصنوعی، یا API داخلی شرکت) وابسته است. وقتی آن سرویس کند یا داون می‌شود، ربات هم کند می‌شود، Timeout می‌دهد و تجربه کاربر نابود می‌شود.

یکی از الگوهای معماری که اینجا واقعاً نجات‌دهنده است، Circuit Breaker Pattern است.

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

• سریع جواب fallback می‌دهد ⚙️
• از شلوغ‌تر شدن سرویس خراب جلوگیری می‌کند 🚫
• ربات شما Responsive باقی می‌ماند ✅

سه حالت اصلی:
• Closed: همه‌چیز اوکی است، درخواست‌ها مستقیم می‌روند.
• Open: خطای زیاد؛ مدار قطع می‌شود، دیگر درخواست مستقیم نمی‌رود.
• Half-Open: هر چند ثانیه چند درخواست تستی می‌فرستد؛ اگر موفق شد، برمی‌گردد به Closed.

نمونه ساده در Python برای ربات تلگرام:

import time
import requests

class CircuitBreaker:
    def __init__(self, failure_threshold=3, reset_timeout=10):
        self.failure_threshold = failure_threshold
        self.reset_timeout = reset_timeout
        self.failures = 0
        self.state = 'CLOSED'
        self.last_failure_time = 0

    def call(self, func, fallback, *args, **kwargs):
        if self.state == 'OPEN':
            if time.time() - self.last_failure_time > self.reset_timeout:
                self.state = 'HALF_OPEN'
            else:
                return fallback()

        try:
            result = func(*args, **kwargs)
            self.failures = 0
            self.state = 'CLOSED'
            return result
        except Exception:
            self.failures += 1
            self.last_failure_time = time.time()
            if self.failures >= self.failure_threshold:
                self.state = 'OPEN'
            return fallback()

cb = CircuitBreaker()

استفاده در هندلر پیام:

def call_ai_service(text):
    return requests.post('https://api.example.com/ai', json={'q': text}).json()

def ai_fallback():
    return {'answer': 'سرویس هوش مصنوعی موقتاً در دسترس نیست 😔'}

# داخل هندلر ربات
response = cb.call(call_ai_service, ai_fallback, message.text)
bot.send_message(chat_id, response['answer'])

نکات کاربردی برای ربات‌های تلگرام:
• برای هر سرویس حساس (پرداخت، AI، CRM) یک Circuit Breaker جدا نگه‌دارید.
• لاگ بگیرید تا بدانید کی مدار Open شده است.
• همراه Circuit Breaker، از Retry با Backoff هم استفاده کنید.


به‌کمک Circuit Breaker ربات‌تان حتی وقتی سرویس‌های بیرونی مشکل دارند، همچنان پایدار و قابل‌اعتماد می‌ماند 💪

🔖 #TelegramBot #ربات #تلگرام #Circuit_Breaker #Resilience #Telegram_Bot #Python #Architecture #Pattern

👤 Developix

💎 Channel: @DevelopixRobot

‏🤖 ساخت ربات آزمون چهارگزینه‌ای در تلگرام با Python

تو خیلی از کانال‌ها و گروه‌ها، ربات‌هایی می‌بینی که آزمون چهارگزینه‌ای (Quiz) برگزار می‌کنن، امتیاز می‌دن و حتی جواب درست رو هم نشون می‌دن. امروز با هم یک نسخه ساده و عملی از همین ایده رو با Python و کتابخونهٔ pyTelegramBotAPI می‌سازیم 😎

ایده اینه:

• کاربر /quiz رو می‌فرسته.
• ربات یک سوال چهارگزینه‌ای با دکمه‌های Inline می‌فرسته.
• با کلیک روی گزینه، ربات می‌گه درست بود یا غلط.

این مدل ربات برای کوییزهای آموزشی، آزمون زبان، تمرین الگوریتم و حتی سرگرمی توی گروه‌ها عالیه.

این کد رو براساس داکیومنت رسمی Bot API و کتابخونهٔ pyTelegramBotAPI نوشتیم و روی BotFather معمولی کاملاً جواب می‌ده ✅

اول با pip نصب کن:

pip install pyTelegramBotAPI

سپس یک فایل مثل quiz_bot.py بساز و این کد رو داخلش بذار (توکن رو از BotFather بردار و جایگزین کن):

import telebot
from telebot import types

API_TOKEN = "YOUR_BOT_TOKEN_HERE"
bot = telebot.TeleBot(API_TOKEN)

# یک سوال نمونه
QUESTION = "کدام زبان برای توسعه ربات تلگرام در این مثال استفاده شده است؟"
OPTIONS = ["Java", "Python", "PHP", "Go"]
CORRECT_INDEX = 1  # Python

@bot.message_handler(commands=["start"])
def send_welcome(message):
    bot.reply_to(message, "سلام! برای شروع آزمون دستور /quiz رو بفرست ✅")

@bot.message_handler(commands=["quiz"])
def send_quiz(message):
    keyboard = types.InlineKeyboardMarkup()
    for i, option in enumerate(OPTIONS):
        btn = types.InlineKeyboardButton(
            text=option,
            callback_data=f"quiz_{i}"
        )
        keyboard.add(btn)

    bot.send_message(
        message.chat.id,
        QUESTION,
        reply_markup=keyboard
    )

@bot.callback_query_handler(func=lambda call: call.data.startswith("quiz_"))
def handle_quiz_answer(call):
    index = int(call.data.split("_")[1])

    if index == CORRECT_INDEX:
        text = "آفرین 🎉 جواب درست بود (Python)."
    else:
        correct_option = OPTIONS[CORRECT_INDEX]
        text = f"❌ نه! جواب درست: {correct_option}"

    # پاسخ به همون پیام
    bot.answer_callback_query(call.id, text, show_alert=True)

if __name__ == "__main__":
    print("Quiz bot is running...")
    bot.infinity_polling()

چند نکتهٔ ریز ولی مهم 👇

• حتماً توکن واقعی ربات رو جایگزین YOUR_BOT_TOKEN_HERE کن.
• اگر روی سرور با محدودیت Network هستی، ممکنه نیاز بشه بجای infinity_polling() از webhook استفاده کنی (طبق داک رسمی: setWebhook).
• می‌تونی لیست OPTIONS و متن QUESTION رو از یک فایل JSON یا دیتابیس بخونی تا رباتت چندین سوال پشت‌سرهم بپرسه.

امتحانش کن، روی چندتا دوستت تست بگیر و بعد کم‌کم امکاناتی مثل نمره‌دهی، رتبه‌بندی و زمان‌بندی آزمون رو بهش اضافه کن 🚀

🔖 #TelegramBot #ربات #تلگرام #Telegram_Bot #Python #pyTelegramBotAPI #Quiz_Bot #InlineKeyboard

👤 Developix

💎 Channel: @DevelopixRobot

‏Idempotency در Webhook ربات تلگرام چیه؟ 🔁

یکی از مشکل‌های رایج تو ربات‌های تلگرام اینه که یه آپدیت چند بار پردازش می‌شه؛ مخصوصاً وقتی:

• سرور delay داره ⏳
• ngrok / proxy قطع و وصل می‌شه
• خودت retry برای request‌هات گذاشتی

اینجاست که مفهوم Idempotency نجاتت می‌ده؛ یعنی اجرای چندبارهٔ یه عملیات، اثر اضافه‌ای نسبت به بار اول نداشته باشه. ✅

در ربات تلگرام، بهترین candidate برای Idempotency همون update_id هر پیام یا callback هست.

ایدهٔ اصلی:

1️⃣ هر update_id رو فقط یه بار قبول کن.
2️⃣ اگر دوباره همون update_id رسید، به‌جای دوباره انجام دادن کار (مثلاً برداشت از کیف پول کاربر)، فقط نتیجهٔ قبلی رو برگردون یا بی‌صدا ignore کن.

یه پیاده‌سازی ساده با Python + Redis 🐍

import time
import redis
from flask import Flask, request

r = redis.Redis(host="localhost", port=6379, db=0)
app = Flask(__name__)

IDEMPOTENCY_TTL = 60 * 5  # 5 دقیقه

@app.post("/webhook")
def telegram_webhook():
    update = request.get_json(force=True)
    update_id = update.get("update_id")

    if update_id is None:
        return "ok"  # ورودی نامعتبر، بی‌صدا رد می‌کنیم

    cache_key = f"tg:update:{update_id}"

    # اگر قبلاً پردازش شده، دوباره انجام نده
    if r.exists(cache_key):
        return "ok"  # idempotent پاسخ

    # قفل سبک برای این update
    with r.lock(f"lock:{cache_key}", timeout=5):
        if r.exists(cache_key):
            return "ok"

        handle_update(update)

        # علامت‌گذاری به‌عنوان پردازش‌شده
        r.setex(cache_key, IDEMPOTENCY_TTL, int(time.time()))

    return "ok"


def handle_update(update: dict) -> None:
    message = update.get("message", {})
    text = message.get("text", "")
    chat_id = message.get("chat", {}).get("id")

    if text == "/start":
        send_welcome(chat_id)


def send_welcome(chat_id: int) -> None:
    # اینجا فراخوانی sendMessage به Bot API رو انجام بده
    ...

نکات مهم در عمل 🚀

• TTL مناسب بذار؛ معمولاً چند دقیقه برای update_id ها کافیه.

• تو عملیات حساس مثل پرداخت، حتماً Idempotency رو تا لایهٔ دیتابیس ادامه بده (مثلاً با unique index روی update_id یا invoice_id).

• اگر از getUpdates هم استفاده می‌کنی، باز همین منطق برای safety بیشتر مفیده.

• تو jobهای async یا queue‌هات (مثل Celery, RQ) هم update_id یا یه idempotency key اختصاصی حمل کن.

پیاده‌سازی درست Idempotency تو Webhook جلوی کلی باگ عجیبی مثل برداشت دوباره، ثبت تکراری سفارش و ارسال چندبارهٔ پیام رو می‌گیره و رباتت رو حسابی قابل‌اعتمادتر می‌کنه ✨

از همین امروز تو لایهٔ Webhook رباتت این الگو رو اضافه کن و ذهنت رو از ترس retryها خلاص کن. 😄

🔖 #TelegramBot #ربات #تلگرام #Idempotency #Telegram_Bot #Webhook #Python #Redis #Clean_Code #Robustness

👤 Developix

💎 Channel: @DevelopixRobot

🎯 ریپلای تمیز توی ربات: همیشه از reply_to_message_id استفاده کن

وقتی ربات توی گروه‌ها شلوغ می‌شود، مهم است جواب هر کاربر دقیقاً زیر پیام خودش بیاید؛ مخصوصاً وقتی چند نفر همزمان از ربات استفاده می‌کنند. به‌جای این‌که فقط به chat تکیه شود، بهتر است همیشه از فیلد reply_to_message_id استفاده شود تا رشتهٔ گفتگو مرتب بماند. 😉

نمونه با Python و python-telegram-bot (v20+):

from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    msg = update.effective_message
    await msg.reply_text(
        "سلام 👋\nدر چه کاری کمک می‌کنم؟",
        reply_to_message_id=msg.message_id
    )

app = ApplicationBuilder().token("YOUR_TOKEN").build()
app.add_handler(CommandHandler("start", start))
app.run_polling()

این کار توی گروه‌ها و سوپرگروه‌ها:

• 📌 جریان گفتگو را واضح نگه می‌دارد.
• 🚫 احتمال اشتباه یا سوتفاهم را کم می‌کند.
• 💬 مخصوصاً برای ربات‌های پشتیبانی، Quiz یا Ticket خیلی حیاتی است.

موقع ارسال پیام با sendMessage در Bot API خام هم کافی است همیشه reply_to_message_id را با message_id پیام کاربر ست کنی.

🔗 مستند رسمی: Telegram Bot API – sendMessage

🔖 #TelegramBot #ربات #تلگرام #Telegram_Bot #reply_to_message_id #python_telegram_bot #group_bots #conversation

👤 Developix

💎 Channel: @DevelopixRobot

‏Command Pattern در معماری ربات تلگرام 🚀

یکی از الگوهای خیلی کاربردی برای تمیز نگه داشتن کد ربات، مخصوصاً وقتی تعداد دستورات زیاد می‌شود، Command Pattern است.

به‌جای اینکه داخل یک فایل بزرگ با کلی if/elif همهٔ دستورها را هندل کنیم، هر دستور را به‌صورت یک «Command» جداگانه پیاده‌سازی می‌کنیم. این کار:

✅ کد را خواناتر و قابل نگه‌داری‌تر می‌کند
✅ اضافه کردن دستور جدید را ساده و بدون دست‌کاری منطق قبلی می‌کند
✅ تست‌نویسی برای هر دستور را راحت‌تر می‌کند

ایدهٔ اصلی Command Pattern 🧠

هر دستور (مثلاً /start، /help، /stats) تبدیل می‌شود به یک کلاس با یک متد ثابت، مثلاً execute().

یک «Command Bus» یا «Dispatcher» فقط تشخیص می‌دهد کاربر چه دستوری داده و Command مناسب را صدا می‌زند؛ خودش منطق دستور را بلد نیست.

نمونهٔ ساده در ربات تلگرام (python-telegram-bot) 🐍

from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes

class BaseCommand:
    async def execute(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
        raise NotImplementedError

class StartCommand(BaseCommand):
    async def execute(self, update, context):
        await update.message.reply_text("سلام 👋 خوش اومدی!")

class HelpCommand(BaseCommand):
    async def execute(self, update, context):
        await update.message.reply_text("لیست دستورات: /start, /help")

class CommandDispatcher:
    def __init__(self):
        self._commands = {
            "start": StartCommand(),
            "help": HelpCommand(),
        }

    async def handle(self, update, context):
        name = update.message.text.lstrip("/").split()[0]
        cmd = self._commands.get(name)
        if cmd:
            await cmd.execute(update, context)

dispatcher = CommandDispatcher()

async def entrypoint(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await dispatcher.handle(update, context)

app = ApplicationBuilder().token("TOKEN").build()
app.add_handler(CommandHandler(["start", "help"], entrypoint))
app.run_polling()

چند نکتهٔ عملی برای ربات‌های واقعی 🛠

• برای هر Command می‌توان وابستگی‌ها را تزریق کرد (Repository، Service، Logger) تا کلاس‌ها تمیز و تست‌پذیر بمانند.

• وقتی تعداد Command ها زیاد شد، می‌توان ثبت آن‌ها را به‌صورت داینامیک (مثلاً با اسکن ماژول‌ها) انجام داد تا دیگر یک دیکشنری بزرگ دستی نگه نداریم.

• در کنار Command Pattern، استفاده از Single Responsibility Principle کمک می‌کند منطق ربات از منطق زیرساخت (HTTP, DB, Cache) جدا بماند.

برای مطالعهٔ بیشتر دربارهٔ این الگو:
refactoring.guru/design-patterns/command

قدم‌به‌قدم که ربات‌تان بزرگ‌تر می‌شود، استفاده از Command Pattern کمک می‌کند معماری کد تمیز بماند و با خیال راحت فیچرهای جدید اضافه کنید ✨

🔖 #TelegramBot #ربات #تلگرام #Command_Pattern #Telegram_Bot #Clean_Code #Python #Design_Patterns #Software_Architecture

👤 Developix

💎 Channel: @DevelopixRobot

💠 نسخه جدید کتابخانه آیوگرام (Aiogram) منتشر شده است

🔸 ارتقا از نسخه 3.29.1 به 3.30.0

🔖 #aiogram, #bot, #python, #release

💎 @DevelopixRobot

🚀 ربات سریع‌تر با استفاده از Webhook به‌جای getUpdates

خیلی از ربات‌ها هنوز با Polling و متد getUpdates کار می‌کنند و هر چند صد میلی‌ثانیه یک‌بار سر می‌زنند ببینند پیام جدیدی آمده یا نه. این کار هم تاخیر را بالا می‌برد، هم روی سرور و هم روی Telegram بار اضافه می‌اندازد.

راه بهتر توی Production استفاده از Webhook است؛ Telegram هر آپدیت را مستقیم به آدرس HTTPS سرور می‌فرستد، بدون Loop و Delay اضافه 👍

نمونه تنظیم Webhook با python-telegram-bot:

from telegram.ext import Application, CommandHandler

TOKEN = "YOUR_BOT_TOKEN"
app = Application.builder().token(TOKEN).build()

async def start(update, context):
    await update.message.reply_text("سلام 👋")

app.add_handler(CommandHandler("start", start))

app.run_webhook(
    listen="0.0.0.0",
    port=8443,
    url_path=TOKEN,
    webhook_url=f"https://example.com/{TOKEN}"
)

نکته مهم 🔐: حتما از HTTPS معتبر استفاده شود و url_path را تصادفی و غیرقابل حدس انتخاب کن تا اسکن‌های ساده به ربات نرسند.

مرجع رسمی: Telegram Bot API – setWebhook

🔖 #TelegramBot #ربات #تلگرام #Telegram_Bot #Webhook #Performance #python_telegram_bot #Security

👤 Developix

💎 Channel: @DevelopixRobot

✏️ ویرایش پیام ربات به‌جای ارسال پیام‌های تکراری

خیلی وقت‌ها ربات برای «وضعیت پردازش»، «نتایج جستجو» یا «پیغام لودینگ» پشت سر هم پیام جدید می‌فرستد و چت را شلوغ می‌کند. یک ترفند ساده این است که به‌جای پیام‌های جدید، همان پیام قبلی را با editMessageText آپدیت کنی. 😉

✅ مزیت‌ها:
• چت تمیزتر و حرفه‌ای‌تر ✨
• مصرف کمتر quota و ترافیک
• تجربه کاربری خیلی روان‌تر

مثال با Python و python-telegram-bot:

from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    msg = await update.message.reply_text("در حال پردازش...")
    # ... کد پردازش ...
    await msg.edit_text("✅ نتیجه آماده شد!")

app = ApplicationBuilder().token("YOUR_TOKEN").build()
app.add_handler(CommandHandler("start", start))
app.run_polling()

نکته 👇
برای ویرایش، باید message_id همان پیام قبلی را داشته باشی (در مثال بالا همون msg). اگر پیام قدیمی خیلی وقت پیش ارسال شده باشد یا کاربر آن را حذف کرده باشد، API خطا برمی‌گرداند؛ بهتر است خطا را لاگ و هندل کنی.

📚 داک رسمی:
EditMessageText - Telegram Bot API


🔖 #TelegramBot #ربات #تلگرام #Telegram_Bot #editMessageText #Python #UX #Chat_Cleanliness #Performance

👤 Developix

💎 Channel: @DevelopixRobot

💠 نسخه جدید کتابخانه آیوگرام (Aiogram) منتشر شده است

🔸 ارتقا از نسخه 3.30.0 به 3.31.0

🔖 #aiogram, #bot, #python, #release

💎 @DevelopixRobot

خیلی وقت‌ها ربات لینک می‌فرستد، اما پیش‌نمایش بزرگ صفحه کل کل چت را شلوغ می‌کند 😅 مخصوصاً برای پیام‌های سیستمی یا دکمه‌دار.

با استفاده از پارامتر disable_web_page_preview در متد sendMessage می‌توان پیش‌نمایش را خاموش کرد تا چت تمیز و فشرده بماند ✅

مثال با Bot API مستقیم:

<code class="language-python">https://api.telegram.org/botTOKEN/sendMessage\
  ?chat_id=123456\
  &text=Check%20this%20link:%20https://example.com\
  &disable_web_page_preview=true</code>

مثال با کتابخانه python-telegram-bot:

<code class="language-python">await context.bot.send_message(
    chat_id=update.effective_chat.id,
    text="لینک مستندات: https://core.telegram.org/bots/api",
    disable_web_page_preview=True,
)</code>

نکته‌ها ✨
• برای پیام‌های اطلاع‌رسانی، دکمه‌ای و لاگ‌ها، تقریباً همیشه گزینه بهتری است.
• برای لینک‌های محتوایی (مقاله، ویدئو) فقط در صورت نیاز خاموش شود تا کاربر پیش‌نمایش را از دست ندهد.

بار بعد که ربات لینک فرستاد و چت شلوغ شد، یک بار این گزینه را تست کن 😉

منبع رسمی: Telegram Bot API - sendMessage

🔖 #TelegramBot #ربات #تلگرام #Telegram_Bot #disable_web_page_preview #sendMessage #python_telegram_bot #UX

👤 Developix

💎 Channel: @DevelopixRobot