آموزش ساخت ربات تلگرام از صفر؛ راهنمای قدم به قدم

در این آموزش ساخت ربات تلگرام را از صفر شروع می‌کنیم؛ ابتدا ربات را در
BotFather می‌سازیم، Token را دریافت و تست می‌کنیم و سپس یک ربات ساده
می‌نویسیم که پیام کاربران را دریافت کند و پاسخ بدهد.

اگر هدفت یادگیری برنامه‌نویسی نیست و برای یک پروژه واقعی به ربات آماده نیاز داری،
می‌توانی صفحه
ساخت ربات تلگرام اختصاصی
را ببینی.

برای ساخت ربات تلگرام به چه چیزهایی نیاز داریم؟

برای ساخت یک ربات ساده به چند بخش اصلی نیاز داریم:

• یک حساب Telegram
• ساخت Bot از طریق BotFather
• دریافت Bot Token
• یک زبان برنامه‌نویسی
• برنامه‌ای برای ارتباط با Telegram Bot API
• در پروژه واقعی، یک سرور یا زیرساخت مناسب برای اجرای دائمی برنامه

در این آموزش برای اینکه منطق کار واضح باشد از Python استفاده می‌کنیم،
اما ساختار اصلی Telegram Bot API به زبان خاصی وابسته نیست و می‌توان با
زبان‌های مختلف به آن درخواست HTTPS ارسال کرد.

ربات تلگرام چگونه کار می‌کند؟

قبل از نوشتن کد بهتر است معماری ساده یک ربات را درک کنیم.

1. کاربر داخل Telegram برای ربات پیام می‌فرستد.
2. Telegram این رویداد را به‌صورت یک Update در اختیار برنامه ربات قرار می‌دهد.
3. برنامه Update را دریافت و بررسی می‌کند.
4. بر اساس پیام کاربر تصمیم می‌گیرد چه کاری انجام شود.
5. برنامه از طریق Bot API درخواست مناسب را برای Telegram ارسال می‌کند.
6. Telegram نتیجه را به کاربر نمایش می‌دهد.

بنابراین خود BotFather برنامه ربات شما نیست. BotFather بیشتر برای ساخت و
مدیریت حساب Bot و تنظیمات آن استفاده می‌شود و منطق اصلی پروژه را باید
در Backend خودتان پیاده‌سازی کنید.

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

داخل Telegram حساب رسمی
@BotFather
را باز کنید.

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

/newbot

BotFather ابتدا از شما نام ربات و سپس Username آن را می‌خواهد.

نام ربات همان عنوانی است که کاربران مشاهده می‌کنند.
Username برای جستجو، Mention و لینک مستقیم ربات استفاده می‌شود.

Username ربات باید منحصربه‌فرد باشد و در انتهای آن
bot
قرار داشته باشد.

برای مثال:

MyShopBot

my_shop_bot

بعد از تکمیل مراحل، BotFather یک Token برای ربات ایجاد می‌کند.

Bot Token چیست؟

Token رشته‌ای است که برنامه شما با استفاده از آن به Telegram ثابت می‌کند
اجازه کنترل آن Bot را دارد.

ساختار آن تقریباً شبیه نمونه زیر است:

1234567890:AAExampleTokenDoNotUseThis123456789

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

بنابراین Token واقعی را داخل مقاله، GitHub عمومی، تصویر، فایل قابل دانلود
یا کدی که در اختیار دیگران قرار می‌دهید منتشر نکنید.

اگر Token ربات لو رفت چه کار کنیم؟

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

از BotFather یک Token جدید ایجاد کنید تا Credential قبلی دیگر برای کنترل
ربات استفاده نشود.

در پروژه واقعی بهتر است Token در متغیر محیطی یا Secret Manager نگهداری شود
و مستقیماً داخل Source Code قرار نگیرد.

مرحله دوم: تست Token با getMe

قبل از برنامه‌نویسی می‌توانیم مطمئن شویم Token کار می‌کند.

قالب اصلی درخواست‌های Bot API به شکل زیر است:

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

برای تست ربات از متد
getMe
استفاده می‌کنیم:

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

به‌جای
<TOKEN>
Token واقعی ربات خودتان را قرار دهید.

اگر Token معتبر باشد، پاسخ JSON شامل اطلاعات پایه ربات دریافت می‌کنید.

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

مرحله سوم: نصب Python برای ساخت ربات

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

برای این آموزش حتی به کتابخانه مخصوص Telegram نیاز نداریم؛
درخواست‌ها را مستقیماً به Bot API ارسال می‌کنیم تا سازوکار اصلی ربات
قابل مشاهده باشد.

یک فایل جدید با نام زیر ایجاد کنید:

bot.py

مرحله چهارم: ارسال اولین پیام با ربات

قبل از اینکه برنامه بتواند پاسخ ارسال کند باید
chat_id
کاربر را بدانیم.

ابتدا ربات خود را در Telegram باز کنید، دکمه Start را بزنید و یک پیام
برای آن ارسال کنید.

سپس این آدرس را با Token خود باز کنید:

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

در داده دریافتی بخشی شبیه
message.chat.id
وجود دارد که شناسه Chat را مشخص می‌کند.

حالا می‌توان با متد
sendMessage
برای همان Chat پیام ارسال کرد.

نوشتن اولین ربات تلگرام با Python

کد زیر یک نمونه آموزشی ساده است که Updateهای جدید را دریافت می‌کند و
به پیام‌های متنی پاسخ می‌دهد.

import json
import time
import urllib.parse
import urllib.request

TOKEN = "YOUR_BOT_TOKEN"
API_URL = f"https://api.telegram.org/bot{TOKEN}"


def telegram_api(method, data=None):
    encoded_data = urllib.parse.urlencode(data or {}).encode()

    with urllib.request.urlopen(
        f"{API_URL}/{method}",
        data=encoded_data,
        timeout=60
    ) as response:
        return json.loads(response.read().decode("utf-8"))


offset = None

while True:
    try:
        params = {
            "timeout": 50
        }

        if offset is not None:
            params["offset"] = offset

        response = telegram_api("getUpdates", params)

        for update in response.get("result", []):
            offset = update["update_id"] + 1

            message = update.get("message")

            if not message:
                continue

            text = message.get("text")

            if text is None:
                continue

            chat_id = message["chat"]["id"]

            if text == "/start":
                reply = "سلام! ربات با موفقیت راه‌اندازی شده است."
            else:
                reply = f"پیام شما: {text}"

            telegram_api(
                "sendMessage",
                {
                    "chat_id": chat_id,
                    "text": reply
                }
            )

    except Exception as error:
        print("Error:", error)
        time.sleep(3)

کد بالا دقیقاً چه کاری انجام می‌دهد؟

قسمت‌های اصلی برنامه را جداگانه بررسی کنیم.

تعریف Token

TOKEN = "YOUR_BOT_TOKEN"

برای تست می‌توانید Token را موقتاً جایگزین کنید، اما در پروژه واقعی
بهتر است Token را از Environment Variable دریافت کنید.

ساخت آدرس Bot API

API_URL = f"https://api.telegram.org/bot{TOKEN}"

تمام متدهای مربوط به Bot با استفاده از همین آدرس پایه فراخوانی می‌شوند.

دریافت Updateها

response = telegram_api("getUpdates", params)

با این درخواست پیام‌ها و رویدادهای جدیدی که Telegram برای Bot در اختیار
برنامه قرار داده دریافت می‌شوند.

مدیریت update_id

offset = update["update_id"] + 1

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

دریافت متن و chat_id

text = message.get("text")
chat_id = message["chat"]["id"]

متن پیام برای تصمیم‌گیری برنامه و
chat_id
برای مشخص کردن مقصد پاسخ استفاده می‌شود.

ارسال پاسخ

telegram_api(
    "sendMessage",
    {
        "chat_id": chat_id,
        "text": reply
    }
)

این بخش متد
sendMessage
را فراخوانی می‌کند و پاسخ را برای همان Chat ارسال می‌کند.

چطور ربات را اجرا کنیم؟

Terminal یا Command Prompt را در پوشه فایل باز کنید و دستور زیر را اجرا کنید:

python bot.py

اگر در سیستم شما دستور Python با نام دیگری ثبت شده باشد ممکن است نیاز باشد
از دستور زیر استفاده کنید:

python3 bot.py

حالا وارد Telegram شوید، ربات را باز کنید و پیام بفرستید.

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

Long Polling چیست؟

روشی که در مثال بالا استفاده کردیم Long Polling است.
برنامه با متد
getUpdates
منتظر Updateهای جدید می‌ماند و بعد از دریافت آن‌ها پردازش را انجام می‌دهد.

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

Webhook چیست؟

در روش Webhook به‌جای اینکه برنامه مرتباً برای دریافت Update به Telegram
درخواست بدهد، یک آدرس HTTPS در اختیار Telegram قرار می‌دهید.

وقتی Update جدیدی ایجاد شود، Telegram آن را به Endpoint تعیین‌شده ارسال می‌کند.

برای سیستم‌های Production که زیرساخت وب مناسب دارند، Webhook می‌تواند
انتخاب مناسبی باشد؛ ولی طراحی Endpoint، امنیت، مدیریت خطا و Deployment
باید درست انجام شود.

Webhook بهتر است یا getUpdates؟

هیچ پاسخ واحدی برای همه پروژه‌ها وجود ندارد.

نکته مهم این است که برای یک Bot نمی‌توان
getUpdates
و Webhook را همزمان برای دریافت Update استفاده کرد.

چرا getUpdates بعد از تنظیم Webhook کار نمی‌کند؟

این یکی از خطاهای رایج هنگام توسعه ربات است.

اگر قبلاً برای Bot یک Webhook تنظیم شده باشد،
getUpdates
روش فعال دریافت Update نخواهد بود.

اگر قصد برگشت به Long Polling را دارید، ابتدا Webhook قبلی را با متد
مربوطه حذف کنید و سپس دریافت Updateها با
getUpdates
را آغاز کنید.

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

ربات‌ها می‌توانند مجموعه‌ای از Commandهای مشخص داشته باشند.

برای مثال:

/start
/help
/products
/profile

این Commandها را می‌توان از تنظیمات BotFather مدیریت کرد و در پروژه‌های
پیشرفته امکان مدیریت آن‌ها از طریق Bot API نیز وجود دارد.

وجود Commandهای مشخص به کاربر کمک می‌کند قابلیت‌های اصلی Bot را
راحت‌تر پیدا کند.

تنظیم توضیحات و پروفایل ربات

بعد از ساخت Bot بهتر است اطلاعات عمومی آن را هم تکمیل کنید.

از جمله:

• نام مناسب
• تصویر پروفایل واضح
• توضیح کوتاه درباره کاربرد ربات
• Description مناسب برای کاربران جدید
• Commandهای اصلی

این موارد روی منطق برنامه تأثیر ندارند، اما تجربه اولین برخورد کاربر
با ربات را بهتر می‌کنند.

اضافه کردن دکمه به ربات تلگرام

ربات حرفه‌ای معمولاً فقط با دستورهای متنی کار نمی‌کند.
Telegram Bot API از Keyboard و Inline Keyboard پشتیبانی می‌کند و
می‌توان مسیرهای کاربری را با دکمه‌ها طراحی کرد.

برای مثال:

• مشاهده محصولات
• ثبت سفارش
• حساب کاربری
• پشتیبانی
• پرداخت

در پروژه‌های بزرگ بهتر است قبل از کدنویسی، Flow کاربر و حالت‌های مختلف
ربات طراحی شوند.

چه زمانی به دیتابیس نیاز داریم؟

برای ربات Echo ساده‌ای که فقط پیام را برمی‌گرداند دیتابیس ضروری نیست.

اما اگر نیاز باشد اطلاعاتی در طول زمان نگهداری شوند، معمولاً باید از
دیتابیس استفاده کنید.

برای مثال:

• ثبت کاربران
• ذخیره سفارش‌ها
• وضعیت پرداخت
• اشتراک کاربران
• تیکت پشتیبانی
• تنظیمات شخصی کاربر
• گزارش‌ها

آیا برای ربات تلگرام به هاست یا سرور نیاز داریم؟

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

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

برای پروژه عملی معمولاً Backend روی سرور، سرویس ابری یا زیرساخت مناسب
دیگری Deploy می‌شود.

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

انتشار Token

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

پردازش دوباره Updateها

اگر Offset در Long Polling درست مدیریت نشود ممکن است بعضی Updateها
دوباره پردازش شوند.

فرض اینکه تمام Updateها پیام متنی هستند

Updateهای Telegram فقط شامل متن نیستند.
ممکن است تصویر، Callback Query، فایل یا انواع دیگری از Event دریافت شود.
بنابراین برنامه باید قبل از دسترسی به فیلدها وجود آن‌ها را بررسی کند.

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

شبکه، API خارجی، دیتابیس یا Telegram ممکن است با خطا مواجه شوند.
یک ربات Production نباید با اولین Exception کاملاً متوقف شود.

ذخیره اطلاعات غیرضروری

فقط داده‌هایی را ذخیره کنید که برای عملکرد واقعی پروژه نیاز دارید و
برای اطلاعات حساس کنترل دسترسی مناسب در نظر بگیرید.

چک‌لیست امنیت ربات تلگرام

• Token را عمومی نکنید.
• Secretها را از Source Code جدا کنید.
• ورودی کاربران را اعتبارسنجی کنید.
• سطح دسترسی مدیران را بررسی کنید.
• خطاهای برنامه را Log کنید.
• اطلاعات حساس را بدون ضرورت ذخیره نکنید.
• در عملیات مالی، وضعیت تراکنش را سمت سرور تایید کنید.
• برای APIهای خارجی Timeout و مدیریت خطا در نظر بگیرید.
• قبل از تغییرات مهم، نسخه آزمایشی ربات داشته باشید.

از ربات ساده تا ربات حرفه‌ای

رباتی که در این آموزش ساختیم فقط نقطه شروع است.
همان ساختار پایه را می‌توان به پروژه‌های بسیار بزرگ‌تر توسعه داد.

برای مثال:

• ربات فروشگاهی تلگرام
• ربات پرداخت تلگرام
• ربات عضویت و اشتراک VIP
• ربات پشتیبانی تلگرام
• ربات مدیریت کاربران
• ربات متصل به سایت و API
• ربات دارای پنل مدیریت
• Telegram Mini App

Mini App چه تفاوتی با ربات معمولی دارد؟

در پروژه‌هایی که دکمه و پیام برای رابط کاربری کافی نیست،
Telegram امکان اجرای Mini App داخل محیط Telegram را فراهم می‌کند.

Mini App می‌تواند رابط HTML5 کامل داشته باشد و برای پروژه‌هایی مثل
فروشگاه، داشبورد، فرم‌های پیچیده و سرویس‌های تعاملی استفاده شود.

با این حال برای همه پروژه‌ها Mini App ضروری نیست و انتخاب آن باید
بر اساس UX و نیاز فنی واقعی انجام شود.

برای ساخت ربات تلگرام چه زبانی بهتر است؟

Bot API به یک زبان برنامه‌نویسی خاص محدود نیست.
بنابراین سؤال اصلی این نیست که «Telegram کدام زبان را قبول می‌کند»،
بلکه باید دید پروژه چه نیازهایی دارد و تیم توسعه با چه تکنولوژی‌ای
می‌تواند سیستم قابل نگهداری‌تری بسازد.

Python، JavaScript/TypeScript، PHP، Java، Go و زبان‌های دیگر می‌توانند
برای ارتباط با Bot API استفاده شوند.

برای پروژه واقعی عواملی مانند اکوسیستم کتابخانه‌ها، تجربه توسعه‌دهنده،
معماری Backend، دیتابیس، Deployment و نگهداری آینده مهم‌تر از انتخاب
یک زبان صرفاً به‌خاطر محبوبیت آن هستند.

سوالات متداول درباره ساخت ربات تلگرام

منابع رسمی برای ادامه یادگیری

برای جزئیات فنی و تغییرات جدید Bot API بهتر است همیشه مستندات رسمی Telegram
را مرجع اصلی قرار دهید.

• 
  Telegram Bot API
  
• 
  آموزش رسمی ساخت اولین Telegram Bot
  
• 
  امکانات Telegram Bots و راهنمای BotFather