ساخت ربات تلگرام از صفر؛ BotFather تا اجرای اولین بات

ربات تلگرام می‌تواند از یک پاسخ‌گوی ساده تا ابزار فروش، پشتیبانی، مدیریت کانال، ثبت سفارش، اطلاع‌رسانی یا اتصال به سرویس‌های دیگر توسعه پیدا کند. ساخت ربات از جایی شروع می‌شود که با BotFather یک Bot ایجاد می‌کنید و Token می‌گیرید؛ اما بخش مهم‌تر بعد از آن است: برنامه‌ای که پیام‌ها را دریافت می‌کند، منطق موردنظر را اجرا می‌کند و از طریق Telegram Bot API پاسخ می‌دهد.

در این راهنما ساخت ربات تلگرام را از صفر توضیح می‌دهیم: ایجاد Bot در BotFather، محافظت از Token، تست API، تفاوت Long Polling و Webhook، نوشتن یک نمونه ساده با Python، تعریف Commandها، استقرار روی سرور و نکات امنیتی. هدف این است که بعد از پایان مقاله فقط یک نام کاربری ربات نداشته باشید، بلکه معماری پشت آن را هم بفهمید.

ربات تلگرام دقیقاً چیست؟

Bot در تلگرام یک حساب ویژه است که توسط نرم‌افزار کنترل می‌شود. برخلاف حساب انسانی، برای ساخت آن شماره تلفن جداگانه لازم ندارید و از طریق API با سرورهای تلگرام ارتباط برقرار می‌کند. کاربر برای ربات پیام می‌فرستد، تلگرام آن Update را در اختیار برنامه شما قرار می‌دهد و برنامه می‌تواند با متدهایی مانند sendMessage پاسخ بدهد.

ربات به‌خودی‌خود «هوشمند» نیست. هوشمندی، دیتابیس، اتصال به درگاه، مدل AI، سیستم امتیازدهی یا هر منطق دیگری را شما در Backend پیاده‌سازی می‌کنید. Telegram Bot API فقط کانال ارتباطی میان برنامه و تلگرام را فراهم می‌کند.

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

در تلگرام حساب رسمی @BotFather را باز کنید. دستور /newbot را ارسال کنید. BotFather ابتدا یک نام نمایشی و سپس Username می‌خواهد. Username ربات باید منحصربه‌فرد باشد و معمولاً به bot ختم شود. پس از تأیید، Token اختصاصی Bot API در اختیار شما قرار می‌گیرد.

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

این Token معادل رمز دسترسی برنامه به ربات است؛ هرکس آن را داشته باشد می‌تواند از طرف Bot درخواست API بفرستد. آن را در اسکرین‌شات، GitHub عمومی، فایل فرانت‌اند یا پیام گروهی قرار ندهید.

در راهنمای رسمی Telegram Bot Platform توضیح داده می‌شود که BotFather نقطه شروع ایجاد و مدیریت Bot است و Token صادرشده باید مانند رمز عبور نگهداری شود. برنامه شما این Token را برای احراز هویت در Bot API به کار می‌برد؛ بنابراین اگر Token افشا شد، صرفاً حذف پیام یا مخزن کافی نیست و باید از BotFather آن را Revoke یا مجدداً تولید کنید تا دسترسی قبلی بی‌اعتبار شود.

Token ربات را کجا نگه داریم؟

در پروژه واقعی Token را داخل کد Hard-code نکنید. آن را در Environment Variable، Secret Manager سرویس میزبان یا فایل .env خارج از Version Control نگه دارید. اگر از فایل .env استفاده می‌کنید، آن را در .gitignore قرار دهید.

TELEGRAM_BOT_TOKEN=123456:YOUR_SECRET_TOKEN

اگر Token قبلاً در یک Commit عمومی منتشر شده باشد، پاک‌کردن Commit به‌تنهایی تضمین نمی‌کند که کسی نسخه قبلی را ندیده باشد. Token را عوض کنید.

مرحله دوم: مطمئن شوید Token درست کار می‌کند

Telegram Bot API ساختار HTTP ساده‌ای دارد. برای تست می‌توانید متد getMe را اجرا کنید. آدرس درخواست به این شکل است:

https://api.telegram.org/bot<TOKEN>/getMe

به جای <TOKEN> مقدار واقعی را فقط در محیط امن خود قرار دهید. پاسخ موفق معمولاً JSON است و اطلاعات Bot مانند ID و Username را برمی‌گرداند. این تست به شما می‌گوید Token معتبر است و اتصال به API برقرار می‌شود.

Update چیست و ربات چگونه پیام را دریافت می‌کند؟

هر رویدادی که تلگرام برای Bot ارسال می‌کند Update نام دارد. پیام متنی، فشردن Inline Button، تغییر وضعیت عضو و رویدادهای دیگر می‌توانند Update تولید کنند. برنامه شما باید این Updateها را دریافت، نوع آن‌ها را تشخیص و منطق مناسب را اجرا کند.

دو روش اصلی برای دریافت Update وجود دارد: Long Polling و Webhook. هر دو معتبرند، اما برای شرایط متفاوت.

Long Polling یا Webhook؛ کدام بهتر است؟

برای یادگیری و اجرای اولین Bot، Long Polling انتخاب راحت‌تری است. وقتی ربات را روی Backend دائمی با دامنه و HTTPS مستقر کردید، Webhook می‌تواند معماری مناسب‌تری باشد. مستندات رسمی Telegram Bots FAQ تفاوت این روش‌ها و محدودیت‌های آن‌ها را توضیح می‌دهد.

ساخت یک ربات ساده با Python

برای درک API لازم نیست از همان ابتدا Framework نصب کنید. با کتابخانه requests می‌توانیم یک پیام ارسال کنیم. ابتدا Python را نصب و سپس در محیط مجازی پروژه، requests را اضافه کنید:

pip install requests

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

import os
import requests

TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]
CHAT_ID = "YOUR_CHAT_ID"

url = f"https://api.telegram.org/bot{TOKEN}/sendMessage"
payload = {
    "chat_id": CHAT_ID,
    "text": "سلام! اولین پیام ربات اجرا شد."
}

response = requests.post(url, json=payload, timeout=20)
response.raise_for_status()
print(response.json())

این مثال فقط ارسال پیام است. برای دریافت پیام با Long Polling می‌توانید از getUpdates استفاده کنید یا برای پروژه واقعی سراغ کتابخانه‌هایی بروید که مدیریت Update، Handler و State را ساده‌تر می‌کنند.

Chat ID را چگونه پیدا کنیم؟

ابتدا به Bot خود یک پیام مثل /start بفرستید. سپس متد getUpdates را فراخوانی کنید. در JSON خروجی، داخل ساختار Message معمولاً اطلاعات Chat و ID را می‌بینید. در گروه‌ها و کانال‌ها نوع و مقدار Chat ID می‌تواند متفاوت باشد؛ بنابراین آن را حدس نزنید و از Update واقعی بخوانید.

ساخت پاسخ‌گوی ساده با Long Polling

منطق پایه این است: آخرین Update ID را نگه دارید، Updateهای جدید را بگیرید، متن را بررسی و پاسخ مناسب را بفرستید. در پروژه واقعی باید خطاهای شبکه، Rate Limit، Restart برنامه و Updateهای غیرمتنی را نیز مدیریت کنید.

import os
import time
import requests

TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]
BASE = f"https://api.telegram.org/bot{TOKEN}"
offset = None

while True:
    params = {"timeout": 30}
    if offset is not None:
        params["offset"] = offset

    data = requests.get(f"{BASE}/getUpdates", params=params, timeout=40).json()

    for update in data.get("result", []):
        offset = update["update_id"] + 1
        message = update.get("message", {})
        text = message.get("text", "")
        chat_id = message.get("chat", {}).get("id")

        if chat_id and text == "/start":
            requests.post(
                f"{BASE}/sendMessage",
                json={"chat_id": chat_id, "text": "ربات آماده است."},
                timeout=20,
            )

    time.sleep(0.2)

این کد آموزشی است، نه معماری کامل Production. برای ربات پرترافیک بهتر است از Framework، Logging، Queue، Database و مدیریت Exception استاندارد استفاده کنید.

Commandهای ربات را در BotFather تعریف کنید

Commandها تجربه کاربری را بهتر می‌کنند و تلگرام آن‌ها را در منوی ربات نمایش می‌دهد. در BotFather از تنظیمات Bot، بخش Commands را باز کنید و دستورهایی مثل موارد زیر تعریف کنید:

start - شروع کار
help - راهنما
profile - پروفایل من
settings - تنظیمات

تعریف Command در BotFather فقط منو و توضیح را می‌سازد؛ منطق اجرای /profile یا /settings همچنان باید در برنامه شما نوشته شود.

دکمه معمولی و Inline Keyboard چه تفاوتی دارند؟

Reply Keyboard جای کیبورد کاربر دکمه‌هایی برای ارسال پیام قرار می‌دهد. Inline Keyboard مستقیماً زیر پیام نمایش داده می‌شود و می‌تواند Callback Data یا URL داشته باشد. برای منوهای تعاملی، تأیید عملیات و Pagination معمولاً Inline Keyboard گزینه تمیزتری است.

برای Callback Query باید بعد از دریافت کلیک، علاوه بر منطق اصلی، به Callback پاسخ بدهید تا حالت Loading دکمه در کلاینت باقی نماند.

Privacy Mode در گروه‌ها چیست؟

ربات‌هایی که به گروه اضافه می‌شوند لزوماً همه پیام‌ها را دریافت نمی‌کنند. Privacy Mode تعیین می‌کند Bot در گروه چه Updateهایی را ببیند. برای بسیاری از ربات‌ها حالت پیش‌فرض امن‌تر و کافی است؛ فقط اگر واقعاً لازم است محتوای عمومی گروه را پردازش کنید تنظیمات را تغییر دهید.

صفحه رسمی Telegram Bot Features قابلیت‌های BotFather، Commandها، Inline Mode و تنظیمات مرتبط را پوشش می‌دهد.

Webhook را چگونه برای Production آماده کنیم؟

در Webhook باید یک Endpoint عمومی HTTPS داشته باشید؛ مثلاً https://example.com/telegram/webhook. تلگرام Update را به این آدرس POST می‌کند. Endpoint باید سریع پاسخ بدهد و پردازش سنگین را بهتر است به Queue منتقل کند تا Timeout و Retry باعث اجرای تکراری عملیات نشود.

برای امنیت، URL تصادفی به‌تنهایی کافی نیست. Secret Token وب‌هوک، اعتبارسنجی Headerهای مرتبط، HTTPS معتبر، محدودسازی دسترسی Backend و ثبت Logهای بدون اطلاعات حساس را در نظر بگیرید. همچنین Handler باید در برابر دریافت دوباره یک Update تا حد امکان Idempotent طراحی شود.

ربات را کجا اجرا کنیم؟

برای تست، لپ‌تاپ شخصی کافی است؛ اما با خاموش شدن دستگاه Bot نیز از کار می‌افتد. برای سرویس دائمی می‌توانید از VPS، Container Platform یا سرویس‌های Serverless/Cloud متناسب با معماری استفاده کنید. هنگام انتخاب میزبان به این موارد دقت کنید:

• امکان تعریف Environment Variable و Secret؛
• HTTPS و دامنه برای Webhook؛
• Log و Monitoring؛
• دیتابیس پایدار؛
• محدودیت Sleep یا زمان اجرای سرویس؛
• موقعیت شبکه و پایداری اتصال به Telegram API.

بدون کدنویسی هم می‌توان ربات ساخت؟

سرویس‌های No-Code برای فرم، منوی ساده، پاسخ خودکار و اتصال محدود به ابزارهای دیگر مناسب‌اند. اگر هدف شما MVP یا عملیات ساده است، می‌توانند زمان راه‌اندازی را کم کنند. اما برای منطق اختصاصی، پردازش داده، دسترسی پیچیده، مقیاس بالا یا کنترل امنیتی، Backend سفارشی انعطاف بیشتری دارد.

نمونه مسیر بدون کدنویسی با FlowXO

سرویس‌هایی مانند FlowXO می‌توانند اتصال ربات تلگرام به جریان‌های آماده، فرم‌ها و پاسخ‌های شرطی را بدون نوشتن یک پروژه کامل ساده کنند. این روش برای نمونه اولیه، ربات پشتیبانی ساده یا آزمایش یک ایده مناسب است؛ بااین‌حال امکانات، قیمت‌گذاری و حتی نام گزینه‌های رابط این سرویس‌ها ممکن است در طول زمان تغییر کند.

این تصاویر یک نمونه رابط بدون کدنویسی را نشان می‌دهند؛ نام گزینه‌ها و چینش سرویس ممکن است با گذشت زمان تغییر کند.

برای رباتی که منطق پیچیده، داده حساس یا حجم پیام بالایی دارد، کنترل مستقیم روی کد و زیرساخت معمولاً انتخاب مطمئن‌تری است. در هر دو حالت Token ربات را مانند رمز عبور نگه دارید و آن را داخل اسکرین‌شات، مخزن عمومی یا فایل قابل دانلود منتشر نکنید.

ساخت منوی ربات با Menu Builder Bot

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

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

قبل از دادن Token به هر سرویس شخص ثالث، اعتبار، سیاست امنیت، امکان حذف داده و سطح دسترسی آن را بررسی کنید. Token ربات یک Secret واقعی است.

اشتباهات رایج در ساخت ربات تلگرام

• قرار دادن Token در GitHub: یکی از رایج‌ترین خطاها و دلیل کافی برای تعویض فوری Token.
• اعتماد به User ID بدون کنترل مجوز: برای دستورات مدیریتی Role و Permission تعریف کنید.
• ذخیره نکردن State: مکالمه چندمرحله‌ای بدون State قابل اتکا نیست.
• پردازش طولانی داخل Webhook: کار سنگین را به Background Job بدهید.
• نداشتن Rate Limit: Bot عمومی باید در برابر Spam و مصرف غیرعادی محافظت شود.
• ثبت اطلاعات حساس در Log: Token، رمز، اطلاعات پرداخت و داده خصوصی را Log نکنید.

ربات هوشمند با AI؛ معماری درست چیست؟

اگر می‌خواهید Bot به مدل زبانی وصل شود، بهتر است پیام کاربر ابتدا به Backend شما برسد. Backend احراز هویت، محدودیت مصرف و تاریخچه لازم را مدیریت می‌کند، سپس درخواست را به سرویس AI می‌فرستد و نتیجه را به تلگرام برمی‌گرداند. کلید API مدل هوش مصنوعی نیز مانند Token تلگرام باید سمت سرور باقی بماند.

برای Botهای عمومی، محدودیت طول ورودی، Moderation متناسب با کاربرد، کنترل هزینه و Timeout ضروری است. همچنین کاربر باید بداند پاسخ خودکار است، مخصوصاً اگر موضوع سرویس حساس یا تصمیم‌ساز باشد.

جمع‌بندی

ساخت ربات تلگرام از BotFather شروع می‌شود، اما کیفیت ربات به معماری پشت آن بستگی دارد. Token را امن نگه دارید، ابتدا با Long Polling منطق را یاد بگیرید، سپس در صورت نیاز به Webhook و استقرار دائمی بروید. Commandها، Inline Buttonها، دیتابیس و اتصال به APIهای خارجی مرحله بعد هستند. اگر از همان پروژه اول مدیریت Secret، Log، خطا و Permission را جدی بگیرید، رباتی می‌سازید که فقط در لپ‌تاپ شما کار نمی‌کند و برای استفاده واقعی نیز قابل توسعه است.