آموزش نصب سورس ربات تلگرام؛ مسیر عملی از فایل سورس تا ربات فعال
وقتی یک سورس ربات تلگرام دریافت میکنید، نصب آن فقط کپیکردن چند فایل روی هاست نیست. سورس باید با نسخه مناسب پایتون یا Node.js اجرا شود، توکن ربات بهشکل امن در تنظیمات قرار بگیرد، کتابخانهها نصب شوند و روش دریافت پیامها (Webhook یا Long Polling) درست انتخاب شود. در این آموزش، مراحل نصب سورس ربات تلگرام را بهصورت عملی و قابل تست بررسی میکنیم تا در پایان، ربات بتواند پیام کاربر را دریافت و پاسخ ارسال کند.
این راهنما بیشتر برای سورسهای Python طراحی شده است، اما منطق کلی آن برای پروژههای PHP، Node.js و سایر زبانها نیز کاربرد دارد. اگر هنوز سورس اختصاصی ندارید و میخواهید ساختار اصولی یک پروژه پایتونی را از ابتدا یاد بگیرید، مقاله آموزش ساخت ربات تلگرام با Python نقطه شروع مناسبی است.
پیشنیازهای نصب سورس ربات تلگرام
پیش از شروع، این موارد را آماده کنید. حذف یا ناقصبودن هر کدام از آنها معمولاً باعث خطا در نصب یا اجرا میشود.
- فایل سورس ربات در قالب ZIP، Git repository یا پوشه پروژه
- توکن معتبر BotFather
- هاست لینوکس، VPS یا سرویس دارای امکان اجرای برنامه
- دسترسی SSH برای نصب مطمئنتر وابستگیها
- دامنه دارای گواهی SSL معتبر، در صورت استفاده از Webhook
- دسترسی به پنل هاست یا تنظیمات DNS
- اطلاعات دیتابیس در صورتی که پروژه از MySQL، PostgreSQL یا Redis استفاده میکند
برای رباتهای ساده، Long Polling روی VPS قابل استفاده است؛ اما در پروژههای فروش، پشتیبانی، ثبت سفارش یا اتصال به API بهتر است Webhook همراه با دامنه و SSL راهاندازی شود. این مدل پایدارتر است و کنترل بهتری روی مسیر درخواستها، لاگها و اتصال به سرویسهای دیگر میدهد. برای نمونه، در یک ربات فروشگاهی تلگرام معمولاً پرداخت، ثبت سفارش، مدیریت موجودی و اعلان مدیر باید به یک جریان قابل اتکا متصل باشند.
مرحله ۱: بررسی ساختار سورس قبل از آپلود
ابتدا فایل ZIP را روی سیستم خودتان استخراج کنید و ساختار پروژه را بررسی کنید. دنبال فایلهای مشخصکننده فناوری و روش اجرا باشید. این کار از آپلود اشتباه یا اجرای دستور نامناسب جلوگیری میکند.
- requirements.txt: معمولاً پروژه Python است.
- package.json: پروژه Node.js است.
- composer.json: پروژه PHP با Composer است.
- .env.example: نمونه متغیرهای محیطی مانند توکن، آدرس دیتابیس و کلیدهای API.
- main.py، bot.py یا app.py: نقطه شروع رایج در Python.
- index.js یا server.js: نقطه شروع رایج در Node.js.
- Dockerfile یا docker-compose.yml: پروژه برای اجرا با Docker آماده شده است.
همچنین فایل README را نادیده نگیرید. توسعهدهنده ممکن است نسخه دقیق پایتون، دستور migration دیتابیس، پورت مورد نیاز یا تنظیمات وبهوک را در آن نوشته باشد. اگر فایل تنظیمات شامل توکن واقعی است، قبل از آپلود آن را حذف کنید یا توکن را تعویض کنید؛ توکن نباید داخل کد عمومی، مخزن عمومی Git یا اسکرینشات قرار بگیرد.
مرحله ۲: ساخت ربات و دریافت توکن از BotFather
در تلگرام، به ربات رسمی BotFather پیام دهید و دستور /newbot را ارسال کنید. نام نمایشی و نام کاربری ربات را انتخاب کنید. نام کاربری باید معمولاً با bot تمام شود. پس از ساخت، BotFather یک توکن بلند در اختیار شما قرار میدهد.
توکن مانند گذرواژه ربات است؛ هر شخصی که به آن دسترسی داشته باشد میتواند از API ربات شما استفاده کند. برای قرار دادن توکن در پروژه، به جای نوشتن مستقیم آن داخل فایل Python، از فایل محیطی استفاده کنید. در ریشه پروژه یک فایل با نام .env بسازید:
BOT_TOKEN=توکن_دریافتی_از_BotFather
ADMIN_IDS=123456789
APP_ENV=productionاگر سورس فایل .env.example دارد، همان فایل را کپی و نام آن را به .env تغییر دهید. کلیدهای اضافی مانند DB_HOST، DB_NAME، PAYMENT_API_KEY یا REDIS_URL را مطابق مستندات سورس تکمیل کنید.
مرحله ۳: آپلود سورس روی هاست یا سرور
برای پروژه حرفهای، SSH و Git بهترین گزینه هستند؛ زیرا بهروزرسانی نسخهها، مشاهده لاگ و نصب وابستگیها را ساده میکنند. اگر فقط cPanel دارید، میتوانید ZIP را در File Manager آپلود و Extract کنید، ولی باید مطمئن شوید فایلها داخل یک پوشه اضافی تو در تو نشدهاند.
نمونه دریافت سورس از Git روی سرور:
cd /var/www
sudo git clone https://github.com/username/telegram-bot.git telegram-bot
cd telegram-bot
ls -laاگر پروژه را با ZIP منتقل میکنید، پس از آپلود بررسی کنید فایلهای اصلی مانند requirements.txt و main.py در مسیر فعلی باشند، نه در مسیری مانند telegram-bot/telegram-bot/main.py. این اشتباه از دلایل متداول خطای «فایل پیدا نشد» در اجرای اولیه است.
مرحله ۴: ساخت محیط مجازی و نصب کتابخانههای Python
برای هر ربات Python یک محیط مجازی مستقل بسازید. محیط مجازی باعث میشود نسخه کتابخانههای یک پروژه با پروژههای دیگر تداخل نداشته باشد. ابتدا نسخه Python را بررسی کنید:
python3 --version
python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txtاگر دستور venv خطا داد، روی سرورهای مبتنی بر Debian یا Ubuntu ممکن است لازم باشد بسته مربوطه نصب شود:
sudo apt update
sudo apt install python3-venv -yپس از نصب، با دستور زیر مطمئن شوید وابستگیهای اصلی نصب شدهاند:
pip listدر cPanel معمولاً از بخش Setup Python App میتوانید نسخه پایتون و محیط مجازی را بسازید. مسیر پروژه، فایل ورودی و متغیرهای محیطی را در همان بخش وارد کنید. با این حال، همه هاستهای اشتراکی امکان اجرای دائمی ربات را ندارند؛ قبل از خرید یا نصب، محدودیت Cron، Process و پورت را بررسی کنید.
مرحله ۵: تنظیم دیتابیس و اجرای Migration
بعضی سورسها اطلاعات کاربران، سفارشها، تیکتها، محصولات یا وضعیت پرداخت را در فایل ذخیره میکنند؛ اما سورسهای قابل توسعه معمولاً دیتابیس دارند. مشخصات دیتابیس را در .env قرار دهید:
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=telegram_bot
DB_USER=bot_user
DB_PASSWORD=رمز_قوی_و_محرمانهاگر پروژه از Django استفاده میکند، معمولاً باید migration اجرا شود:
source venv/bin/activate
python manage.py migrate
python manage.py createsuperuserدر پروژههای دیگر ممکن است فایل SQL مانند database.sql وجود داشته باشد که باید از طریق phpMyAdmin یا خط فرمان import شود. هرگز ساختار دیتابیس را بدون گرفتن نسخه پشتیبان تغییر ندهید؛ مخصوصاً اگر ربات قبلاً سفارش یا اطلاعات کاربر ثبت کرده است.
مرحله ۶: انتخاب بین Long Polling و Webhook
راهاندازی با Long Polling
در Long Polling، برنامه شما دائماً از سرور تلگرام درخواست میکند تا پیامهای جدید را دریافت کند. این روش برای تست اولیه و رباتهای ساده مناسب است. پیش از اجرا مطمئن شوید Webhook قبلی حذف شده باشد:
curl "https://api.telegram.org/botBOT_TOKEN/deleteWebhook?drop_pending_updates=true"سپس فایل اصلی را اجرا کنید:
source venv/bin/activate
python main.pyحالا به ربات پیام /start بدهید. اگر پاسخ دریافت شد، هسته اجرا درست است. ایراد اصلی Long Polling این است که با بستهشدن SSH یا توقف پردازش، ربات خاموش میشود؛ بنابراین برای محیط واقعی باید آن را با systemd، Supervisor یا Docker دائمی کنید.
راهاندازی با Webhook
در Webhook، تلگرام پیام جدید را به یک URL امن در سرور شما ارسال میکند. URL باید HTTPS و دارای گواهی SSL معتبر باشد. نمونه آدرس:
https://example.com/telegram/webhookنمونه ثبت وبهوک با API تلگرام:
curl -F "url=https://example.com/telegram/webhook" \
https://api.telegram.org/botBOT_TOKEN/setWebhookبرای بررسی نتیجه، اطلاعات وبهوک را دریافت کنید:
curl "https://api.telegram.org/botBOT_TOKEN/getWebhookInfo"اگر مقدار last_error_message را مشاهده کردید، معمولاً مشکل از گواهی SSL، مسیر اشتباه، پاسخ ندادن برنامه با HTTP 200 یا مسدودبودن پورت است. مقاله آموزش ساخت ربات تلگرام با Cloudflare Workers بدون نیاز به هاست (راهنمای کامل ۲۰۲۶) نیز یک مسیر جایگزین برای رباتهای وبهوکمحور و سبک ارائه میکند.
مرحله ۷: اجرای دائمی ربات با systemd
اگر ربات با Long Polling کار میکند یا یک وبسرور Python مستقل دارد، از systemd استفاده کنید تا پس از ریاستارت سرور نیز خودکار اجرا شود. ابتدا مسیرهای واقعی پروژه، Python و فایل main.py را پیدا کنید. سپس فایل سرویس را بسازید:
sudo nano /etc/systemd/system/telegram-bot.serviceمحتوای نمونه:
[Unit]
Description=Telegram Bot Service
After=network.target
[Service]
User=www-data
WorkingDirectory=/var/www/telegram-bot
ExecStart=/var/www/telegram-bot/venv/bin/python /var/www/telegram-bot/main.py
Restart=always
RestartSec=5
EnvironmentFile=/var/www/telegram-bot/.env
[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لاگها بخش مهمی از تحویل فنی هستند. در رباتهایی که تیکت، پیام مدیر و وضعیت درخواست دارند، باید خطاها قابل ردیابی باشند. ساختار یک ربات پشتیبانی و تیکت تلگرام زمانی قابل اعتماد است که ارسال پیام، ثبت تیکت، پاسخ اپراتور و گزارش خطا قابل بررسی باشد.
تست نهایی پس از نصب
- دستور /start را برای ربات ارسال کنید.
- دکمههای کیبورد و منوها را تست کنید.
- یک پیام متنی، فایل و تصویر ارسال کنید؛ اگر سورس این قابلیتها را دارد.
- دسترسی مدیر را با شناسه عددی Telegram ID بررسی کنید.
- اگر دیتابیس دارید، ثبت کاربر یا سفارش جدید را کنترل کنید.
- در ربات فروش، مبلغ، وضعیت پرداخت و پیام تأیید را ابتدا در محیط آزمایشی امتحان کنید.
- پس از ریاستارت سرور، وضعیت سرویس و پاسخدهی ربات را دوباره بررسی کنید.
خطاهای رایج در نصب سورس ربات تلگرام
خطای Unauthorized یا Invalid Token
توکن اشتباه است، فاصله اضافی دارد یا در فایل .env بارگذاری نشده است. توکن را از BotFather دوباره کپی کنید، برنامه را ریاستارت کنید و در صورت افشای توکن، با دستور revoke آن را تعویض کنید.
خطای Conflict: terminated by other getUpdates request
بیش از یک نسخه از ربات با Long Polling اجرا شده یا Webhook هنوز فعال است. پردازشهای تکراری را متوقف و Webhook را حذف کنید. برای یافتن پردازشها میتوانید از دستور زیر استفاده کنید:
ps aux | grep python
sudo systemctl restart telegram-botربات روی سرور کار میکند اما در تلگرام پاسخ نمیدهد
لاگ سرویس را بررسی کنید. همچنین مطمئن شوید ربات توسط کاربر Start شده است، هندلر پیام در سورس فعال است و توکن مربوط به همان ربات است. در Webhook، getWebhookInfo بهترین ابزار برای مشاهده خطای آخر است.
ModuleNotFoundError
محیط مجازی فعال نیست یا requirements.txt کامل نصب نشده است. دستور pip install -r requirements.txt را داخل همان venv اجرا کنید و در systemd مسیر Python داخل venv را قرار دهید.
خطای اتصال دیتابیس
نام دیتابیس، کاربر، رمز، پورت یا مجوز دسترسی را بررسی کنید. روی هاست اشتراکی، DB_HOST ممکن است localhost باشد؛ روی سرور یا کانتینر میتواند متفاوت باشد. اطلاعات حساس را در لاگ یا کانال تلگرام منتشر نکنید.
نگهداری، بهروزرسانی و تحویل اصولی
نصب موفق پایان کار نیست. برای ربات عملیاتی باید نسخه پشتیبان دیتابیس، فایل .env، کدهای سفارشی و تنظیمات سرویس را نگه دارید. پیش از هر بهروزرسانی، از نسخه فعال بکاپ بگیرید و ابتدا تغییرات را در محیط تست اجرا کنید. اگر ربات به سایت، CRM، درگاه یا پنل فروش متصل است، تست یکپارچگی را نیز انجام دهید؛ یعنی ثبت سفارش، تغییر وضعیت، ارسال اعلان و برگشت پاسخ API را بررسی کنید.
برای کسبوکارهایی که فروش از سایت و پیامرسان را همزمان مدیریت میکنند، پکیج سایت + ربات فروش میتواند ساختار منسجمتری برای اتصال سفارشها، کاربران و اعلانها فراهم کند. همچنین اگر توسعه شما به پیامرسانهای داخلی گسترش پیدا میکند، مسیرهای پیادهسازی و اتصال در ربات روبیکا و ایتا قابل بررسی است؛ اما توجه داشته باشید API، روش احراز هویت و مدل استقرار هر پلتفرم با تلگرام تفاوت دارد.
جمعبندی
برای نصب سورس ربات تلگرام، ابتدا ساختار پروژه و فایل تنظیمات را بررسی کنید، توکن را فقط در متغیر محیطی قرار دهید، وابستگیها را داخل محیط مجازی نصب کنید و سپس متناسب با زیرساخت، Long Polling یا Webhook را انتخاب کنید. در نهایت اجرای دائمی، لاگگیری، تست دیتابیس و آزمون سناریوی واقعی کاربر را انجام دهید. با این ترتیب، نصب از یک اجرای موقت به یک سرویس قابل نگهداری و قابل توسعه تبدیل میشود.
نظرات کاربران
فقط نظرات تاییدشده مدیر نمایش داده میشود.