ساخت ربات بله با پایتون؛ از توکن تا اجرای دائمی

ساخت ربات بله با پایتون؛ آموزش قدم‌به‌قدم از گرفتن توکن تا اجرای ۲۴ ساعته

فرض کنید فروشگاهتان در بله کانال دارد و هر روز ده‌ها نفر در پیام خصوصی می‌پرسند «سفارشم کجاست؟» یا «ساعت کاری‌تان چیست؟». جواب دادن دستی به این سؤال‌ها بعد از یک هفته خسته‌کننده می‌شود. یک بازوی ساده می‌تواند همین جواب‌ها را با دکمه بدهد، شمارهٔ سفارش بگیرد و حتی پول را با کیف پول بله دریافت کند.

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

بازوی بله چیست و چه فرقی با ربات تلگرام دارد؟

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

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

مورد بازوی بله ربات تلگرام
آدرس API tapi.bale.ai api.telegram.org
ساخت ربات و گرفتن توکن @botfather داخل خود بله @BotFather داخل تلگرام
پورت وب‌هوک فقط 443 و 88 443، 80، 88 و 8443
نگهداری آپدیت‌ها وقتی ربات خاموش است ۲۰۰۰ پیام آخر، تا ۲۴ ساعت تا ۲۴ ساعت
پرداخت داخل ربات کیف پول بله، مبلغ به ریال Telegram Stars و درگاه‌های خارجی
فهرست فرمان‌ها یک فهرست برای همهٔ کاربران قابل تنظیم بر اساس زبان و نوع گفتگو
متدهای اختصاصی askReview، inquireTransaction ندارد

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

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

  • حساب کاربری در پیام‌رسان بله (اپ موبایل یا نسخهٔ وب)
  • پایتون 3.10 یا جدیدتر روی سیستم خودتان؛ نسخه‌های فعلی کتابخانهٔ requests و python-telegram-bot همین حداقل را می‌خواهند
  • آشنایی ابتدایی با اجرای اسکریپت پایتون و نصب پکیج با pip
  • برای اجرای دائمی: یک سرویس پایتون روی هاست ابری یا یک سرور لینوکسی

مرحلهٔ ۱: ساخت بازو در botfather و گرفتن توکن

اولین قدم ساخت ربات بله داخل خود اپ بله انجام می‌شود، نه تلگرام:

  1. در بله عبارت @botfather را جستجو کنید و گفتگو را شروع کنید.
  2. گزینهٔ ساخت بازوی جدید را بزنید، یک نام نمایشی و بعد یک نام کاربری یکتا برای بازو انتخاب کنید.
  3. بعد از ساخت، botfather یک توکن می‌فرستد. شکلش چیزی شبیه 123456789:abcdIuZmK5qNEm2A1BhUaAg7MPJv1O9KCcBQB2ro است.

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

لینک مستقیم بازو هم این شکل را دارد: ble.ir/your_bot_username. اگر به انتهایش ?start=campaign1 اضافه کنید، وقتی کاربر از آن لینک وارد شود، پیام /start campaign1 به ربات می‌رسد و می‌فهمید از کدام تبلیغ یا کانال آمده است.

مرحلهٔ ۲: اولین تست با curl

قبل از نوشتن حتی یک خط پایتون، مطمئن شوید توکن درست است. همهٔ درخواست‌ها به آدرس https://tapi.bale.ai/bot<TOKEN>/METHOD_NAME می‌روند و هم GET و هم POST پذیرفته می‌شود:

export BALE_TOKEN="123456789:your-token-here"

# Check the token
curl "https://tapi.bale.ai/bot$BALE_TOKEN/getMe"

# Send /start to your bot in the app, then read the update to find your chat_id
curl "https://tapi.bale.ai/bot$BALE_TOKEN/getUpdates"

# Send a message to that chat
curl -X POST "https://tapi.bale.ai/bot$BALE_TOKEN/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 123456789, "text": "Hello from my first Bale bot"}'

اگر جواب اولین دستور "ok":true و اطلاعات ربات بود، توکن سالم است. اگر error_code برابر 401 و پیام Unauthorized گرفتید، توکن را اشتباه کپی کرده‌اید یا فاصله‌ای اضافه در آن مانده است.

Long Polling یا Webhook؛ ربات چطور پیام‌ها را بگیرد؟

ربات برای دریافت پیام کاربران دو راه دارد و فقط یکی از آن‌ها را هم‌زمان می‌شود استفاده کرد:

  • Long Polling با getUpdates: ربات مدام از بله می‌پرسد «پیام جدید داری؟». با پارامتر timeout سرور بله تا چند ثانیه جواب را نگه می‌دارد و به محض رسیدن پیام آن را برمی‌گرداند. ربات به دامنه و SSL نیاز ندارد.
  • Webhook با setWebhook: یک بار آدرس HTTPS ربات را به بله می‌دهید و از آن به بعد بله هر آپدیت را با یک درخواست POST برای شما می‌فرستد. مفهوم کلی وب‌هوک را در مقالهٔ Webhook چیست توضیح داده‌ایم.

 

مقایسه Long Polling و Webhook در ساخت ربات بله

 

معیار Long Polling Webhook
نیاز به دامنه و SSL ندارد دارد؛ آدرس باید HTTPS باشد
پورت مهم نیست؛ اتصال از سمت ربات است فقط 443 یا 88
تست روی سیستم شخصی ساده به آدرس عمومی یا تونل نیاز دارد
مدل اجرا یک پردازه که همیشه روشن است اپ وب که با هر درخواست کار می‌کند
مناسب برای اسکریپت پایتون یا Node.js، شروع کار ربات PHP، ربات داخل یک وب‌اپ موجود

برای شروع ساخت ربات بله، Long Polling ساده‌تر است و ادامهٔ این آموزش هم با همین روش جلو می‌رود. اگر بعداً سراغ وب‌هوک رفتید، این سه دستور را لازم دارید:

# Register the webhook (HTTPS, port 443 or 88)
curl "https://tapi.bale.ai/bot$BALE_TOKEN/setWebhook?url=https://bot.example.com/bale"

# Check the current webhook
curl "https://tapi.bale.ai/bot$BALE_TOKEN/getWebhookInfo"

# Remove it before going back to getUpdates
curl "https://tapi.bale.ai/bot$BALE_TOKEN/deleteWebhook"

مرحلهٔ ۳: ربات ساده با پایتون و requests

کوتاه‌ترین راه ساخت ربات بله با پایتون، صدا زدن مستقیم API با کتابخانهٔ requests است. کد زیر به /start خوشامد می‌گوید و هر متن دیگری را عیناً برمی‌گرداند. دو جزئیات مهم دارد: offset بعد از هر آپدیت یک واحد بالا می‌رود تا پیام تکراری نگیرید، و قطعی شبکه با try گرفته می‌شود تا ربات با اولین خطا از کار نیفتد.

import os
import time
import requests

TOKEN = os.environ["BALE_TOKEN"]
API = f"https://tapi.bale.ai/bot{TOKEN}"


def send(chat_id, text):
    requests.post(f"{API}/sendMessage", json={"chat_id": chat_id, "text": text}, timeout=15)


def main():
    offset = 0
    print("bot started", flush=True)
    while True:
        try:
            r = requests.get(
                f"{API}/getUpdates",
                params={"offset": offset, "timeout": 30},
                timeout=40,
            )
            data = r.json()
        except (requests.RequestException, ValueError) as err:
            print("network error:", err, flush=True)
            time.sleep(5)
            continue

        for update in data.get("result", []):
            offset = update["update_id"] + 1
            msg = update.get("message")
            if not msg or "text" not in msg:
                continue
            chat_id = msg["chat"]["id"]
            if msg["text"] == "/start":
                send(chat_id, "Hi! Send me any text and I will echo it.")
            else:
                send(chat_id, msg["text"])


if __name__ == "__main__":
    main()

برای اجرا، پکیج را نصب کنید و توکن را در متغیر محیطی بگذارید:

pip install requests
export BALE_TOKEN="123456789:your-token-here"
python main.py

حالا در بله به ربات پیام بدهید. اگر جواب برگشت، اولین نسخهٔ ربات کار می‌کند. print با flush=True هم عمدی است؛ بعداً روی هاست، همین خروجی‌ها را در بخش لاگ می‌بینید.

مرحلهٔ ۴: ساخت ربات بله با python-telegram-bot

وقتی ربات چند فرمان، دکمه و حالت‌های مختلف پیدا می‌کند، نوشتن حلقهٔ getUpdates با دست شلوغ می‌شود. کتابخانهٔ python-telegram-bot مدیریت آپدیت‌ها، فرمان‌ها و دکمه‌ها را بر عهده می‌گیرد. برای بله کافی است هنگام ساخت Application دو مقدار base_url و base_file_url را روی سرور بله بگذارید؛ کتابخانه توکن را خودش به انتهای آدرس اضافه می‌کند.

import os
from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
from telegram.ext import (
    Application,
    CallbackQueryHandler,
    CommandHandler,
    ContextTypes,
    MessageHandler,
    filters,
)

TOKEN = os.environ["BALE_TOKEN"]


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    keyboard = InlineKeyboardMarkup([
        [InlineKeyboardButton("Plans", callback_data="plans")],
        [InlineKeyboardButton("Support", callback_data="support")],
    ])
    await update.message.reply_text("Welcome! Pick an option:", reply_markup=keyboard)


async def on_button(update: Update, context: ContextTypes.DEFAULT_TYPE):
    query = update.callback_query
    await query.answer()
    if query.data == "plans":
        await query.message.reply_text("Our plans: https://example.com/plans")
    else:
        await query.message.reply_text("Write your question and we will reply soon.")


async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(update.message.text)


def main():
    app = (
        Application.builder()
        .token(TOKEN)
        .base_url("https://tapi.bale.ai/bot")
        .base_file_url("https://tapi.bale.ai/file/bot")
        .build()
    )
    app.add_handler(CommandHandler("start", start))
    app.add_handler(CallbackQueryHandler(on_button))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    app.run_polling()


if __name__ == "__main__":
    main()

فایل requirements.txt این نسخه فقط یک خط دارد:

python-telegram-bot

برای پروژهٔ واقعی نسخه را قفل کنید، مثلاً python-telegram-bot==22.8، تا یک به‌روزرسانی ناگهانی کتابخانه ربات را بعد از ری‌استارت خراب نکند. اگر کد تلگرامی آماده دارید، معمولاً با همین دو خط base_url روی بله هم اجرا می‌شود. بخش‌هایی که به پرداخت یا متدهای خاص تلگرام وابسته‌اند را جدا تست کنید.

دکمه‌ها، منوی فرمان‌ها و قالب‌بندی پیام در بله

چند رفتار بله با تلگرام فرق دارد و اگر ندانید، وقت زیادی سر دیباگ می‌گذارید:

  • دکمهٔ اینلاین منتظر جواب می‌ماند: وقتی کاربر دکمهٔ اینلاین را می‌زند، دکمه تا وقتی answerCallbackQuery صدا زده نشود در حالت انتظار می‌ماند. برای همین در کد بالا await query.answer() اولین خط تابع دکمه است، حتی وقتی پیغامی برای نمایش ندارید.
  • رنگ دکمه: بله برای دکمه‌ها فیلد style با مقدارهای primary، success و danger دارد. این فیلد در کتابخانه‌های تلگرامی تعریف نشده و اگر لازمش دارید، reply_markup را به‌صورت JSON خام بفرستید.
  • منوی فرمان‌ها: با setMyCommands فهرستی مثل start و help تعریف می‌کنید که با تایپ / به کاربر پیشنهاد می‌شود. در بله هر بازو فقط یک فهرست برای همهٔ کاربران دارد و پارامترهای scope و language_code پشتیبانی نمی‌شوند.
  • قالب‌بندی متن: متن پیام‌ها در بله به شکل Markdown قالب‌بندی می‌شود؛ متن بین دو ستاره پررنگ و بین دو زیرخط کج نمایش داده می‌شود. قبل و بعد از علامت‌ها یک فاصله بگذارید.
  • سقف فایل: ربات می‌تواند فایل تا ۵۰ مگابایت آپلود کند و فایل‌های دریافتی را تا ۲۰ مگابایت از طریق getFile دانلود کند.

دریافت پول داخل ربات با کیف پول بله

یکی از دلیل‌هایی که کسب‌وکارها سراغ ساخت ربات بله می‌روند، پرداخت داخل خود پیام‌رسان است. روند کار این است:

  1. از @botfather برای بازو توکن پرداخت کیف پولی می‌گیرید.
  2. با متد sendInvoice پیام «درخواست پول» می‌فرستید. مبلغ در فیلد prices و به ریال تعیین می‌شود.
  3. بعد از تأیید کاربر، یک آپدیت pre_checkout_query می‌رسد. ربات باید حداکثر ظرف ۱۰ ثانیه با answerPreCheckoutQuery جواب بدهد، وگرنه پرداخت لغو می‌شود.
  4. پرداخت فقط وقتی قطعی است که پیام حاوی SuccessfulPayment برسد. برای استعلام بعدی هم متد inquireTransaction وجود دارد.

برای تست، بله توکن WALLET-TEST-1111111111111111 را گذاشته که دقیقاً مثل توکن اصلی رفتار می‌کند ولی پولی جابه‌جا نمی‌کند. شرط ۱۰ ثانیه هم یعنی ربات پرداختی را نباید روی سیستمی اجرا کنید که گاهی خاموش است یا کند جواب می‌دهد.

مرحلهٔ ۵: اجرای ۲۴ ساعته ربات روی هاست

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

گزینه راه‌اندازی نگهداری مناسب برای
سیستم شخصی فوری با خاموش شدن سیستم، ربات هم قطع می‌شود فقط توسعه و تست
سرور مجازی (VPS) نصب پایتون، ساخت سرویس systemd و تنظیم ری‌استارت خودکار آپدیت سیستم‌عامل، امنیت و مانیتورینگ با شماست چند ربات و سرویس کنار هم با کنترل کامل
هاست ابری پایتون (PaaS) آپلود کد و تعریف متغیر محیطی زیرساخت و ری‌استارت با پلتفرم است بیشتر ربات‌ها، از ربات تکی تا ربات کسب‌وکار

اگر سرور مجازی را ترجیح می‌دهید، تفاوت گزینه‌ها را در سرور مجازی (VPS) چیست ببینید. برای بیشتر ربات‌ها اما هاست ابری کار کمتری می‌خواهد. روی سرویس پایتون چابکان مراحل این شکل است:

 

اجرای دائمی پس از ساخت ربات بله روی هاست ابری پایتون

 

  1. از پنل، یک سرویس Python روی هاست پایتون بسازید و نسخهٔ پایتون را 3.10 یا بالاتر انتخاب کنید.
  2. فایل اصلی را main.py نام‌گذاری کنید. طبق مستند اجرای خودکار پایتون، فایلی با این نام بعد از هر روشن شدن یا ری‌استارت سرویس خودش اجرا می‌شود. راه دیگر ساختن فایل start.sh در ریشهٔ برنامه است.
  3. همهٔ پکیج‌ها را در requirements.txt بنویسید. بدون این فایل سرویس اجرا نمی‌شود و پکیج‌های داخلش با هر ری‌استارت خودکار نصب می‌شوند.
  4. در بخش تنظیمات سرویس، متغیر محیطی BALE_TOKEN را اضافه کنید. روش کار در مستند متغیرهای محیطی آمده است. بعد از ذخیره، سرویس دوباره دیپلوی می‌شود.
  5. کد را با CLI، گیت، FTP یا فایل منیجر بفرستید و از بخش لاگ‌ها خروجی bot started را چک کنید. لاگ‌ها فقط چیزی را نشان می‌دهند که در stdout و stderr چاپ شده باشد.

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

اگر می‌خواهید ربات را بدون درگیری با سرور اجرا کنید، هاست ربات بله چابکان برای همین کار ساخته شده و از پایتون، Node.js، Go و PHP پشتیبانی می‌کند. برای ربات‌های PHP که با وب‌هوک کار می‌کنند هاست PHP و برای پروژه‌های جاوااسکریپتی هاست نود جی اس گزینهٔ مستقیم‌تری است. منابع هر پلن در جدول تعرفهٔ همان صفحه آمده و هر وقت ربات شلوغ شد، از پنل قابل ارتقاست. اگر ربات اطلاعات کاربران یا سفارش‌ها را نگه می‌دارد، به‌جای فایل JSON کنار کد یک دیتابیس PostgreSQL جدا بگیرید تا با دیپلوی بعدی داده‌ها پاک نشوند.

خطاهای رایج در ساخت ربات بله

این موارد را از سؤال‌های پرتکرار برنامه‌نویس‌ها جمع کرده‌ایم؛ بیشترشان با یک دستور curl یا نگاه به لاگ پیدا می‌شوند:

  • خطای 401 Unauthorized: توکن اشتباه است یا متغیر محیطی خالی مانده. با getMe توکن را جدا تست کنید.
  • هیچ آپدیتی با getUpdates نمی‌رسد: احتمالاً قبلاً وب‌هوک تنظیم کرده‌اید. با getWebhookInfo چک کنید و اگر آدرسی ثبت شده، deleteWebhook را صدا بزنید.
  • دکمه‌ها روی حالت بارگذاری می‌مانند: answerCallbackQuery فراموش شده است.
  • جواب‌های تکراری یا جاافتاده: ربات با یک توکن هم‌زمان روی دو جا اجرا شده، مثلاً هم روی لپ‌تاپ و هم روی هاست. یک نسخه را خاموش کنید.
  • ربات بعد از مدتی بی‌صدا متوقف می‌شود: لاگ سرویس را ببینید. ری‌استارت‌های پشت‌سرهم معمولاً یعنی حافظه یا پردازنده کم آمده؛ خطای نصب پکیج یعنی requirements.txt ایراد دارد.
  • خطای محدودیت نرخ: اگر پیام زیادی پشت سر هم بفرستید، پاسخ خطا ممکن است فیلد retry_after داشته باشد؛ همان چند ثانیه صبر کنید و دوباره بفرستید. منطق کلی را در Rate Limiting چیست نوشته‌ایم. برای پیام انبوه، بله API کسب‌وکاری جدا با سهمیهٔ بالاتر دارد.

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

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

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

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

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

برای ساخت ربات بله با دکمه و جواب ثابت، دانش پایه‌ای پایتون کافی است و کدهای همین مقاله نقطهٔ شروع خوبی‌اند. اگر اصلاً کد نمی‌نویسید، ابزارهای اتوماسیون مثل n8n می‌توانند با درخواست HTTP به API بله پیام بفرستند.

کتابخانهٔ مخصوص بله برای پایتون لازم است؟

نه. طبق مستندات بله، کتابخانه‌های تلگرامی هم کار می‌کنند. در python-telegram-bot کافی است base_url و base_file_url را روی tapi.bale.ai بگذارید. متدهای اختصاصی بله مثل askReview را باید با درخواست HTTP مستقیم صدا بزنید.

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

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

چرا ربات من پیام‌های دیروز را جواب نداد؟

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

ربات بله را با Webhook بسازم یا Polling؟

برای اسکریپت پایتون یا Node.js که همیشه روشن است، Polling ساده‌تر است و دامنه نمی‌خواهد. اگر ربات بخشی از یک سایت یا اپ PHP است و آدرس HTTPS روی پورت 443 دارد، وب‌هوک منطقی‌تر است.

دیدگاه خود را بنویسید:

آدرس ایمیل شما نمایش داده نخواهد شد.

فوتر سایت