راهنمای ایجاد و راه‌اندازی ربات تلگرام در تله‌ران
در این راهنما، مراحل ساخت ربات تلگرام، دریافت توکن از BotFather، ثبت ربات در تله‌ران و آماده‌سازی آن برای اجرا را بررسی می‌کنیم.
برای راه‌اندازی ربات، به یک حساب تلگرام، دسترسی به BotFather و حساب کاربری تله‌ران نیاز دارید.
فهرست مطالب
- پیش‌نیازها
- مرحله اول: ساخت ربات در تلگرام
- مرحله دوم: دریافت توکن از BotFather
- مرحله سوم: ایجاد ربات در تله‌ران
- مرحله چهارم: تنظیمات اولیه ربات
- مرحله پنجم: آماده‌سازی کد ربات
- مرحله ششم: آزمایش ربات
- رفع خطاهای رایج
- نکات امنیتی
- چک‌لیست راه‌اندازی
پیش‌نیازها
پیش از شروع، موارد زیر را آماده کنید:
- یک حساب کاربری فعال در تلگرام
- دسترسی به ربات رسمی @BotFather
- حساب کاربری در تله‌ران
- نام دلخواه برای ربات
- نام کاربری منحصربه‌فرد برای ربات
- یک توکن معتبر از BotFather
اگر قصد دارید منطق اختصاصی ربات را با کدنویسی پیاده‌سازی کنید، باید کد برنامه و وابستگی‌های موردنیاز آن را نیز آماده داشته باشید.
مرحله اول: ساخت ربات در تلگرام
برای ایجاد یک ربات جدید، ابتدا باید آن را از طریق BotFather ثبت کنید. BotFather ابزار رسمی تلگرام برای ساخت ربات و مدیریت تنظیمات اصلی آن است.
۱. باز کردن BotFather
وارد تلگرام شوید و به حساب رسمی @BotFather مراجعه کنید.
مطمئن شوید حسابی که با آن تعامل دارید، حساب رسمی BotFather است.
۲. شروع فرایند ساخت ربات
دستور زیر را برای BotFather ارسال کنید:
/newbot
BotFather از شما می‌خواهد نام و نام کاربری ربات را وارد کنید.
۳. انتخاب نام ربات
نام ربات، عنوانی است که کاربران هنگام مشاهده پروفایل ربات می‌بینند.
برای مثال:
نام ربات: دستیار هوشمند
نام ربات می‌تواند شامل فاصله و حروف فارسی باشد.
۴. انتخاب نام کاربری ربات
در مرحله بعد، یک نام کاربری یکتا برای ربات انتخاب کنید.
برای مثال:
smart_assistant_bot
نام کاربری ربات باید شرایط تعیین‌شده توسط تلگرام را رعایت کند و معمولاً به bot ختم می‌شود. اگر نام انتخابی قبلاً ثبت شده باشد، باید نام دیگری انتخاب کنید.
نکته: نام نمایشی و نام کاربری دو مقدار متفاوت هستند. نام نمایشی برای معرفی ربات استفاده می‌شود، اما نام کاربری شناسه‌ای است که کاربران می‌توانند از طریق آن ربات را پیدا کنند.
مرحله دوم: دریافت توکن از BotFather
پس از تکمیل مراحل ساخت، BotFather یک توکن دسترسی برای ربات ایجاد می‌کند.
این توکن برای ارتباط برنامه با Telegram Bot API استفاده می‌شود و به برنامه اجازه می‌دهد از طرف ربات درخواست ارسال کند.
نمونه‌ای فرضی از قالب توکن:
123456789:EXAMPLE_TOKEN_DO_NOT_USE
مقدار بالا صرفاً نمونه است و توکن واقعی محسوب نمی‌شود.
توکن را کجا استفاده کنیم؟
توکن در زمان ثبت ربات در تله‌ران وارد می‌شود. در صورت نیاز، برنامه نیز می‌تواند از طریق متغیر محیطی به آن دسترسی داشته باشد.
برای مثال:
TELEGRAM_TOKEN=your_telegram_bot_token
مقدار your_telegram_bot_token را با توکن واقعی خود جایگزین کنید.
نکات مهم درباره توکن
- توکن را در اختیار افراد غیرمجاز قرار ندهید.
- آن را در مخزن عمومی Git یا فایل‌های قابل‌دسترسی عمومی قرار ندهید.
- توکن را در پیام‌های خطا یا گزارش‌های برنامه چاپ نکنید.
- اگر توکن افشا شد، از طریق BotFather آن را لغو یا تعویض کنید و مقدار جدید را در تنظیمات مربوطه قرار دهید.
برای اطلاعات بیشتر، به مستندات امنیت پلتفرم مراجعه کنید.
مرحله سوم: ایجاد ربات در تله‌ران
پس از دریافت توکن، باید ربات را در داشبورد تله‌ران ثبت کنید.
۱. ورود به داشبورد
وارد حساب کاربری خود در تله‌ران شوید.
۲. ایجاد ربات جدید
در داشبورد، گزینه «ربات جدید» را انتخاب کنید.
۳. وارد کردن اطلاعات ربات
اطلاعات موردنیاز را در فرم ایجاد ربات وارد کنید.
| فیلد | توضیح |
|---|---|
| نام ربات | نامی برای شناسایی ربات در داشبورد تله‌ران |
| توکن ربات | توکنی که از BotFather دریافت کرده‌اید |
| سایر تنظیمات | هر گزینه‌ای که در فرم ایجاد ربات نمایش داده می‌شود |
نامی انتخاب کنید که بتوانید ربات را به‌راحتی از سایر پروژه‌های خود تشخیص دهید؛ به‌خصوص اگر چند ربات در تله‌ران مدیریت می‌کنید.
۴. ثبت اطلاعات
پس از بررسی اطلاعات، روی گزینه ایجاد یا ثبت ربات کلیک کنید.
اگر اطلاعات معتبر باشند، ربات در داشبورد ثبت می‌شود.
توجه: نام گزینه‌ها و فیلدهای داشبورد ممکن است با توجه به نسخه رابط کاربری متفاوت باشد. فقط فیلدهایی را تکمیل کنید که در پنل نمایش داده می‌شوند.
مرحله چهارم: تنظیمات اولیه ربات
پس از ایجاد ربات، اطلاعات ثبت‌شده را بررسی کنید و مطمئن شوید ربات به حساب تلگرام موردنظر متصل است.
۱. بررسی توکن
مطمئن شوید توکن واردشده متعلق به همان رباتی است که در BotFather ساخته‌اید.
استفاده از توکن ربات دیگر ممکن است باعث شود پیام‌ها از حساب اشتباه ارسال شوند یا ارتباط با تلگرام برقرار نشود.
۲. بررسی وضعیت ربات
در داشبورد تله‌ران، وضعیت ربات و گزینه‌های موجود برای اجرای آن را بررسی کنید.
اگر پلتفرم وضعیت اجرا یا خطاهای مربوط به ربات را نمایش می‌دهد، پیش از ادامه آن‌ها را بررسی کنید.
۳. آماده‌سازی منطق ربات
ساخت ربات در BotFather و ثبت آن در تله‌ران، به‌تنهایی به معنای پیاده‌سازی تمام قابلیت‌های ربات نیست.
برای پاسخ‌گویی به کاربران، باید منطق موردنیاز را نیز آماده کنید؛ برای مثال:
- پاسخ به دستور
/start - دریافت و پردازش پیام‌های متنی
- نمایش دکمه‌ها و منوها
- مدیریت فرمان‌های اختصاصی
- اتصال به پایگاه داده یا سرویس‌های دیگر، در صورت نیاز
روش افزودن کد و تنظیم نحوه اجرای برنامه باید مطابق قابلیت‌ها و تنظیمات ارائه‌شده در تله‌ران انجام شود.
مرحله پنجم: آماده‌سازی کد ربات
اگر قصد دارید ربات را با پایتون توسعه دهید، می‌توانید از کتابخانه‌هایی مانند aiogram یا python-telegram-bot استفاده کنید.
انتخاب کتابخانه به ساختار برنامه و شیوه اجرای پشتیبانی‌شده در محیط تله‌ران بستگی دارد.
نمونه ساده با Python
نمونه زیر یک ربات ساده با کتابخانه python-telegram-bot ایجاد می‌کند که به دستور /start پاسخ می‌دهد.
import os
from telegram import Update
from telegram.ext import (
Application,
CommandHandler,
ContextTypes,
)
async def start(
update: Update,
context: ContextTypes.DEFAULT_TYPE,
) -> None:
if update.effective_message:
await update.effective_message.reply_text(
"سلام! ربات با موفقیت اجرا شده است."
)
def main() -> None:
token = os.getenv("TELEGRAM_TOKEN")
if not token:
raise RuntimeError(
"متغیر محیطی TELEGRAM_TOKEN تنظیم نشده است."
)
app = Application.builder().token(token).build()
app.add_handler(CommandHandler("start", start))
app.run_polling()
if __name__ == "__main__":
main()
این کد چه کاری انجام می‌دهد؟
- توکن ربات را از متغیر محیطی
TELEGRAM_TOKENمی‌خواند. - در صورت تنظیم‌نشدن توکن، خطای مشخصی ایجاد می‌کند.
- یک برنامه تلگرام ایجاد می‌کند.
- برای دستور
/startیک handler ثبت می‌کند. - با استفاده از Polling، به‌روزرسانی‌های تلگرام را دریافت می‌کند.
- هنگام دریافت
/start، پیام خوشامدگویی ارسال می‌کند.
نکته درباره Polling و Webhook
تلگرام دو روش متداول برای دریافت به‌روزرسانی‌های ربات ارائه می‌دهد:
- Polling: برنامه به‌صورت دوره‌ای به تلگرام درخواست می‌فرستد و به‌روزرسانی‌ها را دریافت می‌کند.
- Webhook: تلگرام به‌روزرسانی‌ها را به یک نشانی HTTPS ثبت‌شده ارسال می‌کند.
کد بالا از Polling استفاده می‌کند. اگر تله‌ران روش اجرای خاصی برای ربات‌ها تعریف کرده باشد، باید کد و تنظیمات خود را مطابق همان روش آماده کنید.
مهم: برای یک ربات نمی‌توان هم‌زمان از Polling و Webhook برای دریافت به‌روزرسانی‌ها استفاده کرد. اگر Webhook برای ربات فعال باشد، ممکن است اجرای Polling با خطا مواجه شود. پیش از تغییر روش دریافت پیام‌ها، تنظیمات فعلی را بررسی کنید.
مرحله ششم: آزمایش ربات
پس از تکمیل تنظیمات و آماده‌سازی کد، عملکرد ربات را آزمایش کنید.
۱. باز کردن ربات در تلگرام
با استفاده از نام کاربری ربات، صفحه آن را در تلگرام باز کنید.
اگر نام کاربری را در اختیار دارید، می‌توانید از نشانی زیر استفاده کنید:
https://t.me/YOUR_BOT_USERNAME
به‌جای YOUR_BOT_USERNAME، نام کاربری واقعی ربات را قرار دهید.
۲. ارسال دستور شروع
در صفحه گفت‌وگو، دکمه شروع را انتخاب کنید یا دستور زیر را بفرستید:
/start
۳. بررسی پاسخ
اگر برنامه به‌درستی اجرا شده باشد و روش دریافت پیام‌ها نیز درست تنظیم شده باشد، ربات باید پیام خوشامدگویی تعریف‌شده در کد را ارسال کند.
۴. بررسی خطاها
اگر پاسخی دریافت نکردید، موارد زیر را بررسی کنید:
- آیا توکن صحیح است؟
- آیا برنامه اجرا شده است؟
- آیا کد به‌درستی بارگذاری شده است؟
- آیا وابستگی‌های موردنیاز نصب شده‌اند؟
- آیا روش دریافت پیام‌ها با تنظیمات ربات مطابقت دارد؟
- آیا خطایی در گزارش‌های اجرا ثبت شده است؟
رفع خطاهای رایج
خطای توکن نامعتبر
نشانه: برنامه نمی‌تواند با Telegram Bot API ارتباط برقرار کند یا درخواست‌ها با خطای احراز هویت مواجه می‌شوند.
راهکار:
- توکن را در BotFather بررسی کنید.
- مطمئن شوید هنگام کپی‌کردن، فاصله یا کاراکتر اضافی وارد نشده است.
- بررسی کنید توکن مربوط به همان ربات ثبت‌شده در تله‌ران باشد.
- اگر توکن قبلاً تعویض شده است، مقدار جدید را در تنظیمات برنامه قرار دهید.
ربات به پیام‌ها پاسخ نمی‌دهد
نشانه: پیام ارسال می‌کنید، اما پاسخی دریافت نمی‌کنید.
راهکار:
- مطمئن شوید برنامه در حال اجراست.
- بررسی کنید handler مربوط به پیام یا دستور موردنظر ثبت شده باشد.
- گزارش‌های برنامه را برای یافتن خطا بررسی کنید.
- روش دریافت به‌روزرسانی‌ها را بررسی کنید.
- اگر از Polling استفاده می‌کنید، مطمئن شوید فرایند دیگری هم‌زمان با همان توکن درخواست دریافت به‌روزرسانی ارسال نمی‌کند.
خطای تداخل Polling
نشانه: برنامه با خطای Conflict یا پیامی درباره استفاده هم‌زمان از getUpdates مواجه می‌شود.
علت احتمالی: بیش از یک فرایند در حال دریافت به‌روزرسانی‌های همان ربات است، یا تنظیمات Webhook با روش Polling تداخل دارد.
راهکار:
- نمونه‌های تکراری برنامه را بررسی کنید.
- مطمئن شوید تنها یک مصرف‌کننده Polling برای ربات فعال است.
- وضعیت Webhook را بررسی کنید.
- روش دریافت به‌روزرسانی‌ها را مطابق تنظیمات محیط اجرا انتخاب کنید.
خطای وابستگی‌های پایتون
نشانه: برنامه با خطاهایی مانند ModuleNotFoundError متوقف می‌شود.
راهکار:
- نام کتابخانه‌ای را که در پیام خطا آمده است بررسی کنید.
- مطمئن شوید وابستگی‌ها در محیط اجرایی درست نصب شده‌اند.
- نسخه پایتون و سازگاری آن با کتابخانه انتخابی را بررسی کنید.
- اگر تله‌ران از فایل مشخصی برای تعریف وابستگی‌ها پشتیبانی می‌کند، کتابخانه‌های لازم را مطابق دستورالعمل همان محیط ثبت کنید.
ربات ساخته شده است، اما در داشبورد وضعیت مناسبی ندارد
راهکار:
- اطلاعات ربات را در داشبورد بررسی کنید.
- از معتبر بودن توکن مطمئن شوید.
- اگر برنامه به فایل یا متغیر محیطی نیاز دارد، وجود آن‌ها را بررسی کنید.
- جزئیات خطاهای نمایش‌داده‌شده در پنل را بررسی کنید.
- در صورت ادامه مشکل، اطلاعات خطا را بدون افشای توکن برای پشتیبانی ارسال کنید.
نکات امنیتی
امنیت توکن و اطلاعات کاربران باید از ابتدای توسعه ربات در نظر گرفته شود.
محافظت از توکن
توکن ربات یک مقدار محرمانه است. آن را در کد عمومی، مخزن عمومی، تصویر صفحه یا گزارش خطا قرار ندهید.
روش پیشنهادی، نگهداری توکن در متغیر محیطی یا بخش امن تنظیمات محیط اجراست.
اعتبارسنجی ورودی کاربران
پیام‌های کاربران را ورودی قابل‌اعتماد فرض نکنید. اگر ربات با پایگاه داده، فایل‌ها یا سرویس‌های دیگر کار می‌کند، ورودی‌ها را متناسب با کاربرد اعتبارسنجی کنید.
محدودکردن دسترسی‌ها
اگر ربات قابلیت‌های مدیریتی دارد، دسترسی به این قابلیت‌ها را به کاربران مجاز محدود کنید. صرف ارسال یک دستور خاص نباید برای انجام عملیات حساس کافی باشد.
محافظت از اطلاعات کاربران
اطلاعاتی را که برای عملکرد ربات ضروری نیستند، جمع‌آوری یا ذخیره نکنید. در صورت نگهداری اطلاعات کاربران، دسترسی به آن‌ها را محدود کنید و سیاست نگهداری اطلاعات را مشخص سازید.
برای جزئیات بیشتر، مستندات امنیت پلتفرم تله‌ران را مطالعه کنید.
چک‌لیست راه‌اندازی
پیش از اعلام آماده‌بودن ربات، موارد زیر را بررسی کنید:
- ربات در BotFather ساخته شده است.
- نام و نام کاربری ربات تنظیم شده‌اند.
- توکن معتبر دریافت شده است.
- ربات در داشبورد تله‌ران ثبت شده است.
- توکن صحیح در تنظیمات مربوطه قرار گرفته است.
- کد ربات آماده و وابستگی‌های آن مشخص شده‌اند.
- روش دریافت به‌روزرسانی‌ها با محیط اجرا سازگار است.
- ربات بدون خطای بحرانی اجرا می‌شود.
- دستور
/startآزمایش شده است. - گزارش‌های اجرا بررسی شده‌اند.
- توکن در کد عمومی یا گزارش‌ها افشا نشده است.
منابع مرتبط
برای تکمیل تنظیمات و آشنایی با بخش‌های دیگر تله‌ران، مستندات زیر را مطالعه کنید: