آموزش استفاده از سورس ربات تلگرام؛ از بررسی فایل‌ها تا اجرا روی هاست

سورس ربات تلگرام چیست و «استفاده از آن» دقیقاً چه مراحلی دارد؟

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

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

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

پیش‌نیازهای لازم پیش از اجرای سورس

• یک ربات ساخته‌شده در BotFather و توکن اختصاصی آن
• دسترسی به سیستم محلی یا هاست لینوکسی با SSH
• نسخه مناسب Python، Node.js، PHP یا زبان استفاده‌شده در پروژه
• دسترسی به دیتابیس در صورت نیاز پروژه؛ مانند MySQL، PostgreSQL، SQLite یا MongoDB
• دامنه دارای HTTPS برای اجرای مبتنی بر وب‌هوک
• ویرایشگر کد مانند VS Code و ابزارهایی مانند Git، ترمینال یا File Manager
• یک شناسه تلگرام مدیر برای محدود کردن دسترسی پنل مدیریتی

قبل از هر تغییری، از فایل اولیه یک نسخه پشتیبان بگیرید. همچنین اگر سورس دارای فایل راهنما، فایل نصب یا نمونه تنظیمات است، ابتدا همان فایل‌ها را مطالعه کنید. نام‌های رایج این فایل‌ها عبارت‌اند از README.md، INSTALL.md، .env.example، requirements.txt، package.json و composer.json.

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

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

telegram-bot/
├── app.py
├── config.py
├── requirements.txt
├── .env.example
├── handlers/
├── services/
├── database/
├── templates/
├── logs/
└── README.md

در یک پروژه پایتون، وجود requirements.txt معمولاً یعنی باید کتابخانه‌ها را با pip نصب کنید. در پروژه Node.js، فایل package.json نقش مشابهی دارد. در پروژه‌های PHP ممکن است پوشه vendor و فایل composer.json وجود داشته باشد. پوشه handlers معمولاً فرمان‌ها و پیام‌های کاربران را پردازش می‌کند، services محل اتصال درگاه، API یا منطق کسب‌وکار است و database شامل مدل‌ها، مهاجرت‌ها یا فایل دیتابیس است.

فایل‌های حساس را پیدا کنید

قبل از اجرا، در فایل‌ها به دنبال کلیدواژه‌های TOKEN، BOT_TOKEN، API_KEY، DATABASE_URL، ADMIN_ID، WEBHOOK_URL، MERCHANT_ID و SECRET بگردید. این مقادیر باید برای محیط خودتان تنظیم شوند. اگر توکن واقعی در سورس وجود دارد، آن را معتبر فرض نکنید و بلافاصله با توکن جدید جایگزین کنید؛ توکن ممکن است قبلاً افشا شده یا متعلق به توسعه‌دهنده قبلی باشد.

مرحله دوم: دریافت توکن جدید از BotFather

1. در تلگرام، ربات رسمی BotFather را باز کنید.
2. دستور /newbot را ارسال کنید.
3. نام نمایشی و نام کاربری یکتای ربات را ثبت کنید؛ نام کاربری باید به bot ختم شود.
4. توکن نمایش‌داده‌شده را در محل امن نگه دارید.
5. در صورت لو رفتن توکن، از دستور /revoke برای ابطال آن استفاده کنید.

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

مرحله سوم: تنظیم متغیرهای محیطی به‌جای قراردادن اطلاعات در کد

روش استاندارد این است که اطلاعات محرمانه در فایل .env نگهداری شوند. اگر پروژه فایل .env.example دارد، آن را کپی کرده و نام نسخه جدید را .env بگذارید.

BOT_TOKEN=توکن_جدید_ربات
ADMIN_IDS=123456789
DATABASE_URL=sqlite:///data/bot.db
WEBHOOK_URL=https://example.com/webhook
PAYMENT_MERCHANT_ID=
LOG_LEVEL=INFO

مقدار ADMIN_IDS باید شناسه عددی تلگرام مدیر باشد، نه نام کاربری. در بسیاری از سورس‌ها این مقدار برای محافظت از دکمه‌های مدیریت، مشاهده سفارش‌ها، ارسال همگانی و ویرایش کالاها استفاده می‌شود. اگر پروژه از چند مدیر پشتیبانی می‌کند، فرمت مورد انتظار را در فایل تنظیمات بررسی کنید؛ گاهی شناسه‌ها با ویرگول انگلیسی جدا می‌شوند.

فایل .env را به فهرست نادیده‌گرفته‌شده Git اضافه کنید:

echo .env >> .gitignore

مرحله چهارم: نصب وابستگی‌ها و اجرای محلی

نمونه اجرای سورس پایتون

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

cd telegram-bot
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python app.py

در ویندوز، فعال‌سازی محیط مجازی معمولاً با دستور زیر انجام می‌شود:

venv\Scripts\activate
pip install -r requirements.txt
python app.py

نمونه اجرای سورس Node.js

cd telegram-bot
npm install
npm run start

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

Polling یا Webhook؛ کدام روش را انتخاب کنیم؟

بیشتر سورس‌های ربات تلگرام با یکی از دو روش Polling و Webhook کار می‌کنند. در Polling، برنامه به‌صورت مداوم از تلگرام پیام‌های جدید را دریافت می‌کند. برای تست روی سیستم شخصی ساده است، اما باید پردازش برنامه دائماً فعال بماند. در Webhook، تلگرام هر پیام را به یک آدرس HTTPS روی سرور شما ارسال می‌کند. این روش برای هاست و استفاده پایدار مناسب‌تر است.

• برای تست اولیه و یادگیری: Polling انتخاب ساده‌تری است.
• برای هاست اشتراکی یا سرور تولیدی: Webhook و دامنه HTTPS انتخاب استانداردتری است.
• هرگز هر دو روش را هم‌زمان برای یک توکن فعال نکنید؛ دریافت آپدیت‌ها دچار تداخل می‌شود.

برای راه‌اندازی دقیق دامنه، SSL، وب‌هوک و بررسی پاسخ سرور، راهنمای آموزش نصب سورس ربات تلگرام روی هاست؛ از تنظیم توکن تا وب‌هوک را دنبال کنید.

مرحله پنجم: اتصال و آماده‌سازی دیتابیس

ربات‌های ساده ممکن است با SQLite کار کنند و تنها با اجرای برنامه فایل دیتابیس را بسازند. اما در ربات فروشگاهی، فروش کانفیگ، تیکت یا ثبت سفارش، معمولاً دیتابیس سروری ضروری است. ابتدا نام دیتابیس، کاربر، رمز و آدرس اتصال را در متغیرهای محیطی وارد کنید؛ سپس در صورت وجود، فایل مهاجرت یا اسکریپت SQL را اجرا نمایید.

CREATE DATABASE telegram_bot CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bot_user'@'localhost' IDENTIFIED BY 'رمز_قوی';
GRANT ALL PRIVILEGES ON telegram_bot.* TO 'bot_user'@'localhost';
FLUSH PRIVILEGES;

سپس، بسته به معماری پروژه، یکی از فرمان‌های مهاجرت را اجرا کنید. مثال زیر فقط نمونه است و باید با مستندات همان سورس تطبیق داده شود:

python manage.py migrate
# یا
alembic upgrade head
# یا
mysql -u bot_user -p telegram_bot < database/schema.sql

در ربات فروش کانفیگ، صرفاً اتصال دیتابیس کافی نیست. باید وضعیت سفارش، مبلغ، شناسه تراکنش، زمان تحویل، وضعیت ارسال و گزارش خطا را به‌صورت جداگانه ذخیره کنید. اطلاعات حساس مشتری و تنظیمات سرویس را حداقلی نگه دارید و دسترسی پنل را فقط به مدیران مجاز محدود کنید.

مرحله ششم: تست سناریوهای واقعی ربات

پس از اجرا، فقط ارسال دستور /start کافی نیست. یک چک‌لیست تست بسازید و هر تغییر را با یک حساب کاربری غیرمدیر نیز بررسی کنید.

1. ارسال /start و نمایش پیام خوش‌آمدگویی
2. درستی دکمه‌های شیشه‌ای و بازگشت به منو
3. ثبت کاربر جدید در دیتابیس
4. بررسی سطح دسترسی مدیر و کاربر عادی
5. ثبت یک سفارش آزمایشی
6. بررسی پیام‌های اعلان برای مدیر
7. تست شکست پرداخت یا لغو فرایند، در صورت وجود درگاه
8. بررسی ثبت لاگ خطا و جلوگیری از نمایش خطای فنی به کاربر
9. تست هم‌زمانی چند کاربر در بخش‌هایی مانند سبد خرید یا تیکت

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

خطاهای متداول هنگام استفاده از سورس ربات تلگرام

خطای Unauthorized یا 401

این خطا معمولاً به توکن نامعتبر، ابطال‌شده یا دارای فاصله اضافی مربوط است. توکن را دوباره از BotFather دریافت و مقدار فایل .env را کنترل کنید. بعد از تغییر فایل تنظیمات، برنامه را یک‌بار کامل متوقف و مجدداً اجرا نمایید.

خطای Conflict: terminated by other getUpdates request

دو پردازش هم‌زمان با Polling در حال استفاده از یک توکن هستند یا وب‌هوک قبلی هنوز فعال است. پردازش‌های قدیمی را متوقف کنید و در صورت مهاجرت به Polling، وب‌هوک را حذف نمایید.

https://api.telegram.org/botYOUR_TOKEN/deleteWebhook

وب‌هوک پاسخ نمی‌دهد

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

ربات اجرا می‌شود اما دکمه‌ها کار نمی‌کنند

نام callback_data، رجیستر نشدن هندلر، ناسازگاری نسخه کتابخانه یا خطا در پردازش وضعیت کاربر را بررسی کنید. برای هر callback یک لاگ کوتاه ثبت کنید تا مشخص شود درخواست به برنامه رسیده است یا خیر.

logger.info('callback_received user_id=%s data=%s', user_id, callback_data)

دیتابیس کار نمی‌کند یا اطلاعات ذخیره نمی‌شوند

مقدار DATABASE_URL، مجوز کاربر دیتابیس، اجرای مهاجرت‌ها و مسیر نوشتن فایل را بررسی کنید. در SQLite، پوشه مقصد باید دسترسی نوشتن داشته باشد. در MySQL و PostgreSQL، علاوه بر نام دیتابیس، میزبان و پورت را نیز کنترل کنید.

آماده‌سازی سورس برای اجرا روی هاست

برای اجرای پایدار، پروژه را با حساب کاربری محدود روی سرور قرار دهید، اطلاعات محرمانه را از کد جدا کنید و لاگ‌ها را قابل مشاهده نگه دارید. در ربات‌های Polling روی VPS، استفاده از سرویس systemd باعث می‌شود برنامه پس از ری‌استارت سرور دوباره بالا بیاید.

[Unit]
Description=Telegram Bot Service
After=network.target

[Service]
User=botuser
WorkingDirectory=/home/botuser/telegram-bot
EnvironmentFile=/home/botuser/telegram-bot/.env
ExecStart=/home/botuser/telegram-bot/venv/bin/python app.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

پس از ذخیره فایل سرویس، فرمان‌های زیر را اجرا کنید:

sudo systemctl daemon-reload
sudo systemctl enable telegram-bot
sudo systemctl start telegram-bot
sudo systemctl status telegram-bot

برای بررسی لاگ زنده نیز از این دستور استفاده کنید:

sudo journalctl -u telegram-bot -f

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

چطور یک سورس آماده را قابل توسعه نگه داریم؟

سورس قابل استفاده فقط سورسی نیست که امروز اجرا شود؛ باید بتوانید فردا قابلیت جدیدی مانند اتصال CRM، درگاه پرداخت، پنل وب، گزارش فروش، اعلان پیامکی یا API تحویل سفارش را به آن اضافه کنید. قبل از تغییر، پروژه را در Git ثبت کنید و تغییرات را در شاخه جدا انجام دهید.

git init
git add .
git commit -m "initial source setup"
git checkout -b feature/order-notification

منطق رابط کاربری، اتصال دیتابیس و فراخوانی API را در یک فایل شلوغ جمع نکنید. برای مثال، پردازش دکمه‌ها در handler، ثبت سفارش در service و دسترسی به داده‌ها در repository یا model قرار گیرد. این تفکیک در زمان رفع باگ، توسعه قابلیت و تحویل پروژه به تیم فنی بسیار ارزشمند است.

اگر هدف شما توسعه برای پیام‌رسان‌های داخلی است

منطق کلی سورس ربات در پلتفرم‌های دیگر مشابه است: دریافت رویداد، اعتبارسنجی کاربر، ذخیره داده، پاسخ‌گویی و مدیریت خطا. با این حال، توکن، API، محدودیت‌های پیام‌رسان، روش وب‌هوک و ساختار دکمه‌ها یکسان نیستند. بنابراین سورس ربات تلگرام را بدون بازنویسی مستقیم برای روبیکا، ایتا یا بله استفاده نکنید.

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

چک‌لیست نهایی قبل از انتشار ربات

• توکن جدید و محرمانه است و داخل کد قرار ندارد.
• فایل .env از مخزن عمومی حذف شده است.
• شناسه مدیران صحیح و محدود است.
• دیتابیس، مهاجرت‌ها و نسخه پشتیبان بررسی شده‌اند.
• Webhook یا Polling فقط در یک حالت فعال است.
• دامنه و SSL در حالت وب‌هوک معتبر هستند.
• لاگ خطا فعال است و اطلاعات محرمانه در لاگ ثبت نمی‌شود.
• فرایند سفارش، پرداخت، لغو و اعلان مدیر تست شده است.
• امکان ری‌استارت خودکار سرویس روی سرور وجود دارد.
• راهنمای نصب، تنظیمات و تحویل برای نگهداری بعدی ثبت شده است.

جمع‌بندی

استفاده صحیح از سورس ربات تلگرام با باز کردن فایل ZIP تمام نمی‌شود. باید فناوری پروژه را تشخیص دهید، توکن و تنظیمات را ایمن وارد کنید، وابستگی‌ها و دیتابیس را آماده سازید، ربات را ابتدا محلی تست کنید و سپس با Polling یا Webhook روی زیرساخت مناسب اجرا نمایید. در پروژه‌های تجاری، کیفیت لاگ‌ها، دسترسی مدیر، نسخه پشتیبان و تست مسیرهای خطا به اندازه منوی ربات و دکمه‌ها اهمیت دارند. با این رویکرد، سورس آماده به یک ربات قابل اتکا، قابل توسعه و قابل تحویل تبدیل می‌شود.