آموزش ساخت ربات بله با Python و TeleBot؛ اتصال pyTelegramBotAPI به Bale API

اگر قصد دارید یک ربات بله (Bale Bot) با زبان Python بسازید، می‌توانید از کتابخانه محبوب TeleBot یا pyTelegramBotAPI استفاده کنید. از آنجا که API پیام‌رسان بله شباهت زیادی به Telegram Bot API دارد، با یک تغییر در آدرس API می‌توان ساختار آشنای TeleBot را برای توسعه ربات‌های بله به کار گرفت.

در این آموزش، قدم‌به‌قدم یاد می‌گیریم چگونه یک ربات پیام‌رسان بله با Python بسازیم، API بله را به TeleBot متصل کنیم، پیام‌های کاربران را دریافت کنیم و به آن‌ها پاسخ دهیم.

در پایان نیز نحوه اجرای ربات روی پلتفرم تله‌ران را بررسی می‌کنیم تا برای اجرای دائمی ربات نیازی به راه‌اندازی و مدیریت مستقیم VPS نداشته باشید.

ربات بله چیست؟

ربات‌های بله برنامه‌هایی هستند که می‌توانند به‌صورت خودکار با کاربران تعامل داشته باشند و وظایف مختلفی را انجام دهند؛ برای مثال:

• پاسخ‌گویی خودکار به پیام کاربران
• ارسال اعلان و Notification
• ساخت منوهای تعاملی
• مدیریت خدمات و کاربران
• ارسال فایل و تصویر
• اتصال به APIهای دیگر
• اتصال به دیتابیس
• ارائه خدمات مبتنی بر هوش مصنوعی
• ساخت سیستم‌های پشتیبانی و خدمات مشتریان

اگر با توسعه ربات‌های تلگرام آشنا باشید، ساختار Bale Bot API برایتان تا حد زیادی آشنا خواهد بود.

در این آموزش از Python و کتابخانه pyTelegramBotAPI (TeleBot) استفاده می‌کنیم.

پیش‌نیازهای ساخت ربات بله با Python

برای شروع به موارد زیر نیاز دارید:

• Python نسخه 3.8 یا بالاتر
• یک ربات ساخته‌شده در پیام‌رسان بله
• Bot Token
• کتابخانه pyTelegramBotAPI

برای نصب TeleBot، دستور زیر را اجرا کنید:

pip install pyTelegramBotAPI

اگر قصد دارید Token را در فایل .env نگهداری کنید، کتابخانه python-dotenv را نیز نصب کنید:

pip install python-dotenv

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

ابتدا باید یک ربات در پیام‌رسان بله ایجاد کنید.

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

برای مثال:

YOUR_BALE_BOT_TOKEN

نکته امنیتی: Bot Token را مانند رمز عبور در نظر بگیرید و آن را در کد عمومی، GitHub یا شبکه‌های اجتماعی منتشر نکنید.

مرحله دوم: تغییر API تلگرام به API بله

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

در ابتدای برنامه این کد را قرار دهید:

from telebot import apihelper

apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"

این خط باعث می‌شود درخواست‌هایی که TeleBot ارسال می‌کند، به API بله فرستاده شوند.

به عبارت ساده، به‌جای اینکه TeleBot با سرورهای تلگرام ارتباط برقرار کند، درخواست‌ها را به سرورهای بله ارسال خواهد کرد.

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

حالا یک فایل با نام bot.py ایجاد کنید.

کد زیر یک ربات ساده می‌سازد که به دستور /start پاسخ می‌دهد و سایر پیام‌های متنی کاربر را نیز بازتاب می‌دهد:

import telebot
from telebot import apihelper

TOKEN = "YOUR_BALE_BOT_TOKEN"

# تغییر API از Telegram به Bale
apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"

bot = telebot.TeleBot(TOKEN)


@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(
        message,
        "سلام! ربات بله شما فعال شد."
    )


@bot.message_handler(func=lambda message: True)
def echo(message):
    bot.reply_to(
        message,
        f"شما گفتید: {message.text}"
    )


print("Bot is running...")
bot.infinity_polling()

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

مرحله چهارم: اجرای ربات بله

برای اجرای ربات، در ترمینال وارد پوشه پروژه شوید و دستور زیر را اجرا کنید:

python bot.py

اگر برنامه بدون خطا اجرا شود، پیام زیر را مشاهده خواهید کرد:

Bot is running...

حالا وارد پیام‌رسان بله شوید و به ربات خود پیام بدهید.

با ارسال:

/start

باید پاسخ زیر را دریافت کنید:

سلام! ربات بله شما فعال شد.

اگر پیام دیگری ارسال کنید، ربات آن را به شکل زیر بازمی‌گرداند:

شما گفتید: سلام

بررسی بخش‌های مهم کد

حالا قسمت‌های اصلی برنامه را بررسی کنیم.

تعریف Bot Token

TOKEN = "YOUR_BALE_BOT_TOKEN"

این متغیر Token ربات شما را نگهداری می‌کند.

Token مشخص می‌کند برنامه شما با کدام ربات در بله ارتباط برقرار کند.

تغییر آدرس API

مهم‌ترین بخش اتصال TeleBot به بله این قسمت است:

apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"

به‌صورت پیش‌فرض TeleBot برای Telegram Bot API تنظیم شده است.

با تغییر API_URL، درخواست‌های کتابخانه به API بله ارسال می‌شوند.

بنابراین این خط یکی از مهم‌ترین تفاوت‌های بین یک پروژه TeleBot معمولی و یک پروژه ربات بله با TeleBot است.

ساخت شیء ربات

bot = telebot.TeleBot(TOKEN)

این دستور یک نمونه از TeleBot ایجاد می‌کند و Token ربات را به آن می‌دهد.

از این شیء برای دریافت پیام، ارسال پاسخ و مدیریت رویدادهای مختلف استفاده می‌کنیم.

دریافت دستور /start

این بخش:

@bot.message_handler(commands=["start"])

به TeleBot می‌گوید هر زمان کاربر دستور /start را ارسال کرد، تابع مربوط به آن را اجرا کند.

تابع مربوطه:

def start(message):
    bot.reply_to(
        message,
        "سلام! ربات بله شما فعال شد."
    )

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

دریافت پیام‌های دیگر

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

@bot.message_handler(func=lambda message: True)

این Handler برای دریافت پیام‌های متنی عمومی استفاده می‌شود.

در مثال ما، متن پیام کاربر با:

message.text

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

اجرای دائمی ربات

در انتهای برنامه داریم:

bot.infinity_polling()

این دستور باعث می‌شود برنامه به‌صورت مداوم منتظر پیام‌های جدید بماند.

در نتیجه تا زمانی که برنامه در حال اجرا باشد، ربات می‌تواند پیام‌های جدید را دریافت و پردازش کند.

استفاده از فایل .env برای امنیت بیشتر

قرار دادن Bot Token مستقیماً داخل فایل Python برای پروژه‌های واقعی توصیه نمی‌شود.

بهتر است Token را در متغیر محیطی یا فایل .env قرار دهید.

ابتدا کتابخانه مورد نیاز را نصب کنید:

pip install python-dotenv

سپس یک فایل با نام:

.env

ایجاد کنید:

BALE_TOKEN=YOUR_BALE_BOT_TOKEN

حالا کد Python را به شکل زیر تغییر دهید:

import os

import telebot
from dotenv import load_dotenv
from telebot import apihelper


load_dotenv()

TOKEN = os.getenv("BALE_TOKEN")

apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"

bot = telebot.TeleBot(TOKEN)


@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(
        message,
        "سلام! ربات بله شما فعال شد."
    )


@bot.message_handler(func=lambda message: True)
def echo(message):
    bot.reply_to(
        message,
        f"شما گفتید: {message.text}"
    )


print("Bot is running...")
bot.infinity_polling()

این روش باعث می‌شود Token از کد اصلی پروژه جدا باشد.

همچنین اگر پروژه را با Git مدیریت می‌کنید، بهتر است .env را به .gitignore اضافه کنید:

.env

به این ترتیب Token به‌صورت تصادفی وارد مخزن Git نمی‌شود.

اجرای ربات بله روی پلتفرم تله‌ران

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

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

تله‌ران امکان اجرای پروژه را روی زیرساخت ابری فراهم می‌کند و برای شروع نیز اعتبار اولیه رایگان (Free Starter Credit) در اختیار کاربران قرار می‌دهد.

بنابراین می‌توانید ابتدا ربات بله خود را ایجاد و تست کنید و سپس پروژه را روی تله‌ران اجرا کنید.

روند کلی

ساختار کار به این صورت است:

Python Code
     ↓
TeleBot
     ↓
Bale Bot API
     ↓
تله‌ران
     ↓
اجرای دائمی ربات

فایل‌های پروژه خود را آماده کنید، وابستگی‌ها را در requirements.txt قرار دهید و Token را به‌صورت Environment Variable تنظیم کنید.

برای مثال، فایل requirements.txt می‌تواند شامل موارد زیر باشد:

pyTelegramBotAPI
python-dotenv

البته اگر Token را مستقیماً به‌عنوان Environment Variable در محیط اجرای پروژه تنظیم کنید، دیگر الزاماً نیازی به python-dotenv در محیط production نخواهید داشت.

چرا Environment Variable مهم است؟

بهتر است Bot Token را داخل فایل پروژه قرار ندهید.

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

BALE_TOKEN=YOUR_BALE_BOT_TOKEN

و در Python آن را با:

import os

TOKEN = os.getenv("BALE_TOKEN")

دریافت کنید.

این روش برای پروژه‌هایی که روی سرویس‌های ابری اجرا می‌شوند، امنیت و مدیریت تنظیمات بهتری فراهم می‌کند.

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

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

ربات هیچ پاسخی نمی‌دهد

اگر ربات شما پاسخی نمی‌دهد، موارد زیر را بررسی کنید:

• Token صحیح باشد.
• آدرس API بله به‌درستی تنظیم شده باشد.
• برنامه Python در حال اجرا باشد.
• اتصال اینترنت محیط اجرای برنامه برقرار باشد.
• ربات در بله به‌درستی ساخته شده باشد.
• خطایی در Console یا Log برنامه وجود نداشته باشد.

خطای API دریافت می‌کنم

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

برای مثال:

1. دریافت پیام
2. ارسال پیام
3. پاسخ به پیام کاربر
4. اجرای دستور /start

دلیل این کار این است که همه قابلیت‌های Telegram Bot API الزاماً در بله دقیقاً به یک شکل پیاده‌سازی نشده‌اند.

بنابراین بهتر است ابتدا قابلیت‌های پایه را تست کرده و سپس امکانات پیچیده‌تر را به پروژه اضافه کنید.

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

پس از ساخت نسخه اولیه، می‌توانید قابلیت‌های بسیار بیشتری به ربات اضافه کنید.

برای مثال:

دیتابیس

می‌توانید اطلاعات کاربران، سفارش‌ها، تنظیمات و سوابق فعالیت را در دیتابیس ذخیره کنید.

منوی دکمه‌ای

می‌توانید برای ربات منو و دکمه‌های تعاملی ایجاد کنید تا کاربر بدون تایپ دستورات مختلف با ربات کار کند.

هوش مصنوعی

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

سیستم پرداخت

برای پروژه‌های تجاری می‌توانید قابلیت‌های مربوط به پرداخت و مدیریت سفارش را به ربات اضافه کنید.

ارسال فایل و تصویر

ربات می‌تواند علاوه بر پیام متنی، بسته به قابلیت‌های API مورد استفاده، فایل‌ها و رسانه‌های مختلف را نیز مدیریت کند.

پنل مدیریت

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

ساختار پیشنهادی پروژه

برای یک پروژه واقعی، بهتر است همه کدها را در یک فایل قرار ندهید.

برای مثال:

bale-bot/
│
├── bot.py
├── handlers/
│   ├── start.py
│   ├── messages.py
│   └── admin.py
│
├── services/
│   └── ai.py
│
├── database/
│   └── database.py
│
├── requirements.txt
├── .env
└── .gitignore

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

جمع‌بندی

ساخت ربات بله با Python و TeleBot می‌تواند بسیار ساده باشد؛ به‌خصوص اگر قبلاً با pyTelegramBotAPI و ربات‌های تلگرام کار کرده باشید.

مهم‌ترین تغییر برای استفاده از TeleBot با API بله، تنظیم آدرس API است:

from telebot import apihelper

apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"

پس از آن می‌توانید از ساختار آشنای TeleBot برای تعریف Handlerها، دریافت پیام‌ها و پردازش دستورات استفاده کنید.

یک نمونه کامل و ساده:

import telebot
from telebot import apihelper

TOKEN = "YOUR_BALE_BOT_TOKEN"

apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"

bot = telebot.TeleBot(TOKEN)


@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "سلام! ربات بله شما فعال شد.")


@bot.message_handler(func=lambda message: True)
def echo(message):
    bot.reply_to(message, f"شما گفتید: {message.text}")


print("Bot is running...")
bot.infinity_polling()

اگر می‌خواهید این پروژه را به‌صورت دائمی اجرا کنید، می‌توانید کد خود را روی پلتفرم تله‌ران اجرا کنید و برای شروع از اعتبار اولیه رایگان (Free Starter Credit) آن استفاده کنید.

به این ترتیب، مسیر کلی شما از ساخت ربات تا اجرای آن به شکل زیر خواهد بود:

ساخت Bot در بله
        ↓
دریافت Bot Token
        ↓
نصب pyTelegramBotAPI
        ↓
تغییر API_URL به Bale API
        ↓
نوشتن Handlerها
        ↓
تست ربات
        ↓
Deploy روی تله‌ران
        ↓
اجرای ربات

سوالات متداول

آیا می‌توان با TeleBot برای بله ربات ساخت؟

بله. با توجه به سازگاری API بله با ساختار Telegram Bot API، می‌توان با تغییر آدرس API از ساختار pyTelegramBotAPI برای توسعه ربات بله استفاده کرد.

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

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

آیا می‌توان Token ربات بله را داخل کد قرار داد؟

از نظر فنی بله، اما برای پروژه‌های واقعی بهتر است Token را در Environment Variable یا فایل .env قرار دهید و آن را در Git یا کد عمومی منتشر نکنید.

آیا برای اجرای ربات بله به VPS نیاز دارم؟

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

آیا می‌توان ربات بله را به هوش مصنوعی متصل کرد؟

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

آیا ساخت ربات بله با Python سخت است؟

برای یک ربات ساده، خیر. با pyTelegramBotAPI می‌توانید Handlerهای مختلفی تعریف کنید و منطق ربات را به‌تدریج توسعه دهید. پیچیدگی پروژه بیشتر به امکاناتی مانند دیتابیس، پرداخت، پنل مدیریت و سرویس‌های خارجی بستگی دارد.