ساخت ربات بله با هوش مصنوعی: آموزش گام‌به‌گام با پایتون و n8n

ساخت ربات بله با هوش مصنوعی: آموزش گام‌به‌گام با پایتون و n8n

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

تیم ژرف۲۵ آبان ۱۴۰۵۴۳ دقیقه

برای ساخت ربات بله با هوش مصنوعی سه قطعه لازم است: بازویی که در خود بله از بازوی پدر (BotFather) می‌سازید و توکنش را می‌گیرید، برنامه‌ای کوچک که پیام‌ها را از API بازوی بله بخواند و جواب بفرستد، و یک مدل زبانی که پیام کاربر را بفهمد و پاسخ فارسی بنویسد. API بله روی HTTPS ساده کار می‌کند و طبق مستندات رسمی بازوی بله بر پایه API بات تلگرام و با تغییرات جزئی ساخته شده است؛ پس با پایتون، PHP، سی‌شارپ یا n8n می‌شود به آن وصل شد. در این آموزش هر سه قطعه را گام‌به‌گام می‌سازیم و در پایان یک دستیار فارسی دارید که جواب می‌دهد، چند پیام اخیر هر گفت‌وگو را به خاطر می‌سپارد و وقتی مدل در دسترس نیست ساکت نمی‌ماند.

در بله به ربات «بازو» می‌گویند؛ پس هر جا «ربات بله»، «بات بله»، «بازوی بله» یا «چت بات بله» دیدید، منظور یک چیز است. این راهنما در ۲۵ آبان ۱۴۰۵ (۱۶ نوامبر ۲۰۲۶) با مستندات بازو، پرسش‌های متداول و قوانین بله، مستندات n8n و Ollama و کد منبع n8n تطبیق داده شد. مخاطبش برنامه‌نویس یا مدیر فنی‌ای است که می‌خواهد دستیاری واقعی برای کسب‌وکارش بسازد، نه فقط یک نمونه نمایشی. کدهای پایتون و PHP این صفحه را روی یک شبیه‌ساز محلی اجرا کردیم که پاسخ‌های مستند API بله و یک سرور مدل ساختگی را تقلید می‌کند؛ آن‌ها را با یک بازوی واقعی آزمایش نکرده‌ایم و هر جا مستندات بله ساکت یا متناقض بود، همان را صریح نوشته‌ایم.

ربات بله چیست و API بازو چه امکاناتی می‌دهد

بازو حسابی است که به جای انسان، برنامه شما آن را می‌گرداند. هر پیامی که کاربر به بازو می‌فرستد یک «آپدیت» می‌سازد و برنامه شما آن را به یکی از دو روش دریافت می‌کند: با فراخوانی پیاپی getUpdates یا با وب‌هوک، یعنی نشانی‌ای روی سرور شما که بله آپدیت‌ها را به آن می‌فرستد. پرسش‌های متداول بله تصریح می‌کند که این دو روش را نمی‌شود هم‌زمان به کار برد. اگر برنامه شما مدتی خاموش باشد، به گفته مستندات، سرور بله ۲۰۰۰ آپدیت آخر را تا ۲۴ ساعت نگه می‌دارد.

هر درخواست به شکل https://tapi.bale.ai/bot<token>/METHOD_NAME فرستاده می‌شود. هر دو روش GET و POST پذیرفته می‌شوند و پارامترها را می‌توان در رشته پرس‌وجو، فرم معمولی، JSON یا multipart/form-data فرستاد؛ آخری برای بارگذاری فایل است. پاسخ همیشه JSON است و فیلد ok دارد. اگر درخواست موفق باشد نتیجه در result می‌آید و اگر نه، error_code و description و گاهی parameters.retry_after برمی‌گردد. نام متدها به بزرگی و کوچکی حروف حساس نیست و همه متن‌ها باید UTF-8 باشند.

آنچه بازو می‌تواند دریافت کند متن، عکس، فایل، صدا، پیام صوتی، ویدیو، استیکر، مخاطب، موقعیت مکانی و پیام‌های پرداخت است. برای تعامل هم دو نوع دکمه وجود دارد: صفحه‌کلید پاسخ که جای کیبورد کاربر می‌نشیند و می‌تواند شماره تماس یا موقعیت را با اجازه کاربر بفرستد، و دکمه‌های شیشه‌ای زیر پیام که پیوند باز می‌کنند، مینی‌اپ را اجرا می‌کنند، متنی را رونوشت می‌کنند یا داده‌ای بین ۱ تا ۶۴ بایت را به بازو برمی‌گردانند. پس از فشردن دکمه شیشه‌ای، دکمه در حالت انتظار می‌ماند تا بازو answerCallbackQuery را صدا بزند؛ این فراخوانی را حتی وقتی پیامی برای نمایش ندارید فراموش نکنید.

همه امکانات تلگرام در بله نیست. پرسش‌های متداول بله می‌گوید بسیاری از متدها هنوز در حال توسعه‌اند و مستندات هم چند تفاوت را نام برده است؛ مثلاً هر بازو فقط یک فهرست فرمان برای همه کاربران دارد و پارامترهای scope و language_code تلگرام در setMyCommands پشتیبانی نمی‌شوند. در مقابل، بله متدهایی دارد که در کتابخانه‌های تلگرام نیست، مانند askReview برای نمایش فرم امتیازدهی.

این عددها را پیش از طراحی بدانید. ستون منبع مهم است، چون صفحه‌های رسمی بله در چند مورد با هم یکی نیستند:

موضوعمقدارمنبع
طول متن یک پیام۱ تا ۴۰۹۶ نویسهمستند sendMessage
آپدیت‌های دریافت‌نشده۲۰۰۰ آپدیت آخر، تا ۲۴ ساعتمستندات بازو
تعداد آپدیت در هر getUpdates۱ تا ۱۰۰، پیش‌فرض ۱۰۰مستند getUpdates
نمایش وضعیت «در حال نوشتن»حداکثر ۶ ثانیهمستند sendChatAction
دانلود فایل با getFileتا ۲۰ مگابایت؛ پیوند دانلود یک ساعت معتبر استمستند getFile
ارسال فایلمستندات: عکس تا ۱۰ و بقیه تا ۵۰ مگابایت (از راه نشانی اینترنتی ۵ و ۲۰)؛ پرسش‌های متداول: تا ۵۰۰ مگابایتهر دو صفحه
نرخ ارسال به یک گفت‌وگوصفحه توسعه‌دهندگان: بهتر است زیر ۲ پیام در ثانیه بمانید و سقف دقیق ۲۰ پیام در ثانیه و ۱۲۰ در دقیقه است؛ پرسش‌های متداول: سقف ۲ در ثانیه و ۱۲۰ در دقیقهصفحه توسعه‌دهندگان بله و پرسش‌های متداول
درگاه‌های وب‌هوکمستندات: ۴۴۳ و ۸۸؛ پرسش‌های متداول: ۴۴۳، ۸۰، ۸۸ و ۸۴۴۳مستندات و پرسش‌های متداول

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

ساخت ربات بله و گرفتن توکن از BotFather

  1. در اپلیکیشن بله، روی گوشی یا رایانه، پیوند ble.ir/botfather را باز کنید. صفحه بازو این معرفی را نشان می‌دهد: «سلام من بات پدر هستم. شما میتوانید با من بات های خودتان را بسازید و مدیریت کنید. برای نمایش لیست تمام کامند های من /help را بفرستید!»

  2. گفت‌وگو را شروع کنید و /start را بفرستید. بازوی پدر با دکمه کار می‌کند: گزینه ساخت بازوی جدید را بزنید و به پرسش‌هایش جواب دهید. آخرین پرسش، نام کاربری بازوست. این نام بعداً در پیوند ble.ir/<bot_username> دیده می‌شود، پس کوتاه و خوانا انتخابش کنید. مستندات نوشتاری بله متن این گفت‌وگو را منتشر نکرده است؛ آنچه در این بخش می‌خوانید از ساختن یک بازوی آزمایشی در ۲۵ آبان ۱۴۰۵ آمده و ممکن است بعداً عوض شود. اگر می‌خواهید مراحل را پیش از شروع ببینید، طبق توضیح صفحه دوره‌های آموزشی بله، ویدئوی «مینی‌اپ در بله: از توسعه تا اجرا» ساختن بازو در بازوی پدر را هم نشان می‌دهد.

  3. پس از فرستادن نام کاربری، بازوی پدر پیام «بازوی شما با موفقیت ساخته شد!» را می‌فرستد. این پیام سه چیز دارد: «نام بازو» که همان نام کاربری با @ است، «لینک دسترسی» به شکل ble.ir/<bot_username> و «توکن دسترسی». زیر پیام، دکمه «رونوشت توکن» توکن را کپی می‌کند. طبق مستندات، توکن از یک عدد، یک دونقطه و یک رشته طولانی از حروف و رقم ساخته شده است؛ چیزی به شکل 123456789: و پس از آن چند ده نویسه. همین پیام یادآوری می‌کند که بازو فقط وقتی در جست‌وجوی بله دیده می‌شود که بیش از ۲۰ کاربر ماهانه داشته باشد. پس تا آن زمان بازو را با پیوند مستقیمش باز کنید و همین پیوند را به کاربران بدهید. بعد از این پیام، بازوی پدر منوی مدیریت همان بازو را نشان می‌دهد، با دکمه‌هایی مثل «ویرایش بازو»، «مدیریت کامندها»، «عضویت بازو در گروه»، «تنظیمات مینی‌اپ»، «پرداخت در بازو»، «دریافت نظرات»، «بازیابی توکن» و «حذف بازو».

  4. توکن را بیازمایید. نشانی زیر را با توکن خودتان در مرورگر باز کنید یا در ترمینال اجرا کنید:

    bash
    export BALE_TOKEN='123456789:replace-with-your-token'
    curl -sS "https://tapi.bale.ai/bot$BALE_TOKEN/getMe"
    

    اگر توکن درست باشد، پاسخی با "ok":true می‌گیرید که در result شناسه عددی بازو، is_bot برابر true، نام و نام کاربری آن آمده است. اگر توکن نادرست باشد، مستند getMe می‌گوید error_code برابر 401 و توضیح Unauthorized برمی‌گردد.

  5. فهرست فرمان‌ها را تنظیم کنید تا کاربر با نوشتن / آن‌ها را ببیند. نام هر فرمان ۲ تا ۳۲ نویسه از حروف لاتین، عدد و زیرخط است:

    bash
    curl -sS "https://tapi.bale.ai/bot$BALE_TOKEN/setMyCommands" \
      -H 'Content-Type: application/json' \
      -d '{"commands":[{"command":"start","description":"شروع گفت‌وگو"},{"command":"reset","description":"پاک کردن حافظه گفت‌وگو"},{"command":"human","description":"گفت‌وگو با همکار انسانی"}]}'
    

توکن کلید کامل بازوست: هر کس آن را داشته باشد می‌تواند به نام بازوی شما پیام بفرستد و پیام‌های کاربرانش را بخواند. آن را در کد، مخزن گیت یا گروه کاری نگذارید. پرسش‌های متداول بله می‌گوید اگر توکن را گم کردید، با باطل کردن توکن قبلی در بازوی پدر توکن جدید بگیرید؛ اگر لو رفت، همین کار را بی‌درنگ انجام دهید. منوی مدیریت بازو برای این کار دکمه «بازیابی توکن» را دارد. یک نکته هم برای آینده: قوانین بله بازوها را بسته به تعامل کاربران در دو سطح تعریف می‌کند و بازویی که کاربرانش زیاد شود، برای ادامه فعالیت باید با احراز هویت توسعه‌دهنده در همان بازوی پدر ارتقا پیدا کند. به گفته همین قوانین، زمان اجرایی شدن این قاعده در کانال «اخبار بازو» (ble.ir/botnews) اعلام می‌شود. در آزمایش ما در ۲۵ آبان ۱۴۰۵ این ارتقا در خود بازوی پدر در دسترس بود. بازوی پدر توضیح می‌دهد که هر بازو از ابتدا در سطح یک است و فقط بازوهای سطح دو می‌توانند در بله معرفی شوند، مثلاً در صفحه خدمات یا تبلیغ. برای ارتقا، کد ملی دارنده شماره همراهی را که در بله ثبت شده و تاریخ تولد او را می‌خواهد و پس از آن اعلام می‌کند که همه بازوهای آن توسعه‌دهنده، از جمله بازوهایی که بعداً بسازد، در سطح دو هستند.

ساخت ربات بله با پایتون: اولین بازو با getUpdates

پیش از هوش مصنوعی، یک بازوی پژواک بسازید که هر متنی را عیناً برگرداند. این بازو سه چیز را با هم آزمایش می‌کند: توکن، دسترسی شبکه سرور به tapi.bale.ai و حلقه دریافت آپدیت. کد زیر فقط از کتابخانه استاندارد پایتون ۳ استفاده می‌کند و به نصب هیچ بسته‌ای نیاز ندارد؛ این روی سرورهای داخلی که دسترسی‌شان به مخزن بسته‌های پایتون همیشه پایدار نیست، یک مزیت واقعی است. آن را در فایلی به نام bale_echo.py ذخیره کنید:

Python
import http.client
import json
import os
import sys
import time
import urllib.error
import urllib.request

TOKEN = os.environ.get("BALE_TOKEN", "")
API = f"https://tapi.bale.ai/bot{TOKEN}"
ERRORS = (OSError, ValueError, KeyError, TypeError, RuntimeError, http.client.HTTPException)


def bale(method, payload=None, timeout=15):
    """Call one Bale Bot API method and return its result field."""
    request = urllib.request.Request(
        f"{API}/{method}",
        data=json.dumps(payload or {}).encode("utf-8"),
        headers={"Content-Type": "application/json"},
    )
    try:
        with urllib.request.urlopen(request, timeout=timeout) as response:
            body = json.load(response)
    except urllib.error.HTTPError as error:
        body = json.loads(error.read() or b"{}")
    if not body.get("ok"):
        raise RuntimeError(f"{method}: {body.get('error_code')} {body.get('description')}")
    return body["result"]


def main():
    if not TOKEN:
        sys.exit("Set BALE_TOKEN first.")
    me = bale("getMe")
    print("Connected as", me.get("username"))
    offset = None
    while True:
        params = {"timeout": 30}
        if offset is not None:
            params["offset"] = offset
        try:
            updates = bale("getUpdates", params, timeout=40)
        except ERRORS as error:
            print("getUpdates failed:", error, file=sys.stderr)
            time.sleep(5)
            continue
        for update in updates:
            offset = update["update_id"] + 1
            message = update.get("message") or {}
            text = message.get("text")
            if not text:
                continue
            try:
                bale("sendMessage", {"chat_id": message["chat"]["id"], "text": text})
            except ERRORS as error:
                print("sendMessage failed:", error, file=sys.stderr)


if __name__ == "__main__":
    main()

اجرایش ساده است:

bash
export BALE_TOKEN='123456789:replace-with-your-token'
python3 bale_echo.py

ترمینال سطر Connected as را همراه نام کاربری بازو چاپ می‌کند. حالا در بله به بازو پیام بدهید تا همان را پس بگیرید. سه جزء این کد ارزش توضیح دارند:

  • انتظار طولانی (long polling). پارامتر timeout در getUpdates به سرور بله می‌گوید تا ۳۰ ثانیه منتظر پیام تازه بماند و بعد پاسخ خالی بدهد. مهلت خود درخواست را ۴۰ ثانیه گذاشته‌ایم تا همیشه از انتظار سرور بیشتر باشد.
  • تأیید آپدیت با offset. مستند getUpdates می‌گوید offset باید یکی بیشتر از بزرگ‌ترین update_id دریافت‌شده باشد و با آن، آپدیت‌های قبلی تأییدشده حساب می‌شوند. اگر این را جا بیندازید، پرسش‌های متداول بله توضیح می‌دهد که همان ۱۰۰ آپدیت اول صف دوباره و دوباره برمی‌گردد.
  • خطای شبکه برنامه را نمی‌کشد. هر قطعی یا پاسخ نامعتبر فقط پنج ثانیه مکث می‌آورد و حلقه ادامه پیدا می‌کند. خطای توکن در getMe اما عمداً برنامه را متوقف می‌کند تا مشکل پیکربندی دیده شود.

ساخت ربات بله با هوش مصنوعی: وصل کردن مدل زبانی

حالا به جای پژواک، متن کاربر را به یک مدل زبانی می‌دهیم. کد زیر با هر سروری کار می‌کند که رابط تکمیل گفت‌وگوی سازگار با OpenAI، یعنی مسیر /v1/chat/completions، داشته باشد. انتخاب مدل با شماست و سه مسیر مشروع دارد:

  • مدل روی رایانه یا سرور خودتان. با Ollama یک مدل باز را محلی اجرا کنید؛ نصب و انتخاب مدل در آموزش نصب Ollama آمده است. مستند سازگاری Ollama با OpenAI نشانی پایه http://localhost:11434/v1/ را به کار می‌برد و می‌گوید کلید API لازم است اما سرور محلی آن را نادیده می‌گیرد.
  • ارائه‌دهنده داخلی. چند ارائه‌دهنده ایرانی نقطه دسترسی سازگار با OpenAI می‌فروشند. پیش از انتخاب، پرسش‌هایی را که در راهنمای دسترسی به API هوش مصنوعی در ایران آورده‌ایم بپرسید؛ مهم‌ترینش این است که مدل از نظر فیزیکی کجا اجرا می‌شود.
  • هر ارائه‌دهنده‌ای که شرایطش استفاده شما را مجاز بداند. برای بازویی که کاربرانش در ایران‌اند این شرط تعیین‌کننده است. برای نمونه، صفحه کشورهای پشتیبانی‌شده OpenAI ایران را فهرست نکرده و هشدار می‌دهد دسترسی یا فراهم کردن دسترسی بیرون از این کشورها ممکن است به مسدود شدن حساب برسد.

این فایل را bale_ai_bot.py بنامید:

Python
import hashlib
import http.client
import json
import os
import re
import sys
import threading
import time
import urllib.error
import urllib.request
from collections import OrderedDict, deque

BALE_TOKEN = os.environ.get("BALE_TOKEN", "")
BALE_API = f"https://tapi.bale.ai/bot{BALE_TOKEN}"
LLM_BASE_URL = os.environ.get("LLM_BASE_URL", "http://localhost:11434/v1").rstrip("/")
LLM_API_KEY = os.environ.get("LLM_API_KEY", "local")
LLM_MODEL = os.environ.get("LLM_MODEL", "")
OPERATOR_CHAT_ID = os.environ.get("OPERATOR_CHAT_ID", "")
ERRORS = (OSError, ValueError, KeyError, IndexError, TypeError, AttributeError,
          RuntimeError, http.client.HTTPException)

SYSTEM_PROMPT = (
    "تو دستیار پاسخ‌گوی «فروشگاه نمونه» در پیام‌رسان بله هستی. "
    "کوتاه، مؤدبانه و به فارسی روان جواب بده؛ حداکثر پنج جمله. "
    "متن ساده بنویس و از ستاره، علامت # و جدول برای قالب‌بندی استفاده نکن. "
    "فقط درباره محصولات، ارسال و ساعت کاری فروشگاه حرف بزن و برای موضوع‌های دیگر "
    "مؤدبانه بگو در این زمینه کمکی از تو برنمی‌آید. "
    "اگر جواب را مطمئن نمی‌دانی حدس نزن؛ بگو با فرستادن /human پیام به همکار انسانی می‌رسد. "
    "هرگز رمز، شماره کارت، کد یک‌بارمصرف یا کد ملی از کاربر نخواه."
)
WELCOME = (
    "سلام! من دستیار خودکار فروشگاه نمونه هستم و با هوش مصنوعی جواب می‌دهم، "
    "پس ممکن است اشتباه کنم. برای گفت‌وگو با همکار انسانی /human "
    "و برای شروع دوباره /reset را بفرستید."
)
BUSY = "الان نمی‌توانم جواب بدهم. چند دقیقه دیگر دوباره بپرسید یا /human را بفرستید."
SLOW_DOWN = "پیام‌ها خیلی سریع رسیدند. یک دقیقه صبر کنید و دوباره بپرسید."
NO_OPERATOR = "فعلاً همکار انسانی به این بازو وصل نیست. لطفاً بعداً دوباره بپرسید."

MAX_TURNS = 6           # user/assistant pairs remembered for each chat
MAX_CHATS = 1000        # chats kept in memory; the least recently active is forgotten first
MAX_INPUT_CHARS = 1500  # longer messages are cut before they reach the model
MAX_PER_MINUTE = 6      # messages accepted from one chat per minute
MAX_WAIT = 30           # longest pause after a 429 from Bale, in seconds
TEXT_LIMIT = 4000       # Bale accepts up to 4096 characters per message

chats = OrderedDict()    # chat id -> recent turns and message times, oldest chat first
lock = threading.Lock()  # the webhook version calls handle() from several threads


def log(event, chat_id=None, **fields):
    """Record what happened, never what anyone wrote."""
    if chat_id is not None:
        fields["chat"] = hashlib.sha256(str(chat_id).encode()).hexdigest()[:12]
    print(json.dumps({"t": int(time.time()), "event": event, **fields}), file=sys.stderr)


def post_json(url, payload, headers, timeout):
    request = urllib.request.Request(
        url,
        data=json.dumps(payload).encode("utf-8"),
        headers={"Content-Type": "application/json", **headers},
    )
    try:
        with urllib.request.urlopen(request, timeout=timeout) as response:
            return json.load(response)
    except urllib.error.HTTPError as error:
        return json.loads(error.read() or b"{}")


def bale(method, payload=None, timeout=15):
    for attempt in range(3):
        body = post_json(f"{BALE_API}/{method}", payload or {}, {}, timeout)
        if body.get("ok"):
            return body["result"]
        retry_after = (body.get("parameters") or {}).get("retry_after")
        if body.get("error_code") == 429 and retry_after and attempt < 2:
            time.sleep(min(int(retry_after), MAX_WAIT))
            continue
        raise RuntimeError(f"{method}: {body.get('error_code')} {body.get('description')}")


def ask_model(messages):
    body = post_json(
        f"{LLM_BASE_URL}/chat/completions",
        {"model": LLM_MODEL, "messages": messages, "temperature": 0.3},
        {"Authorization": f"Bearer {LLM_API_KEY}"},
        timeout=120,
    )
    answer = (body["choices"][0]["message"].get("content") or "").strip()
    if not answer:
        raise ValueError("empty answer from the model")
    return answer


def plain_text(text):
    """Bale renders its own Markdown, so drop the model's."""
    text = re.sub(r"\*\*|__|`+", "", text)
    text = re.sub(r"^#{1,6}[ \t]*", "", text, flags=re.MULTILINE)
    text = re.sub(r"^[ \t]*[*-][ \t]+", "• ", text, flags=re.MULTILINE)
    return re.sub(r"\n{3,}", "\n\n", text).strip() or "…"


def send_long(chat_id, text):
    """Send the answer in pieces Bale accepts, cut at a paragraph, a line or a word."""
    while text:
        cut = len(text)
        if cut > TEXT_LIMIT:
            cut = TEXT_LIMIT
            for separator in ("\n\n", "\n", " "):
                found = text.rfind(separator, TEXT_LIMIT // 2, TEXT_LIMIT)
                if found != -1:
                    cut = found
                    break
        bale("sendMessage", {"chat_id": chat_id, "text": text[:cut]})
        text = text[cut:].lstrip()


def chat_state(chat_id):
    """This chat's memory; only the MAX_CHATS most recently active chats are kept."""
    with lock:
        state = chats.pop(chat_id, None) or {"turns": deque(maxlen=MAX_TURNS * 2), "times": deque()}
        chats[chat_id] = state
        while len(chats) > MAX_CHATS:
            chats.popitem(last=False)
        return state


def over_limit(state):
    """Count this message; return how far the chat is over MAX_PER_MINUTE (0 if not)."""
    now = time.monotonic()
    with lock:
        times = state["times"]
        while times and now - times[0] > 60:
            times.popleft()
        times.append(now)
        return max(0, len(times) - MAX_PER_MINUTE)


def handle(message):
    chat = message.get("chat") or {}
    if chat.get("type") != "private":
        return
    chat_id = chat["id"]
    text = (message.get("text") or "").strip()
    state = chat_state(chat_id)

    excess = over_limit(state)
    if excess:
        if excess == 1:  # say it once, then stay quiet until the chat slows down
            bale("sendMessage", {"chat_id": chat_id, "text": SLOW_DOWN})
        log("rate_limited", chat_id)
        return
    if not text:
        bale("sendMessage", {"chat_id": chat_id, "text": "فعلاً فقط پیام متنی را می‌فهمم."})
        return
    if text.startswith("/start") or text == "/reset":
        with lock:
            state["turns"].clear()
        bale("sendMessage", {"chat_id": chat_id, "text": WELCOME})
        return
    if text == "/human":
        reply = NO_OPERATOR
        if OPERATOR_CHAT_ID:
            user = message.get("from") or {}
            name = re.sub(r"[\[\]()*_`]", "", user.get("first_name", ""))  # user-chosen text
            username = f" @{user['username']}" if user.get("username") else ""
            try:
                bale("sendMessage", {"chat_id": OPERATOR_CHAT_ID,
                                     "text": f"درخواست گفت‌وگو با انسان: {name}{username}، شناسه گفت‌وگو {chat_id}"})
                reply = "پیامتان به همکار ما رسید و در ساعت کاری جواب می‌گیرید."
                log("handoff", chat_id)
            except ERRORS as error:  # a wrong group ID, or the bot is not in the group
                log("handoff_failed", chat_id, kind=type(error).__name__)
        bale("sendMessage", {"chat_id": chat_id, "text": reply})
        return

    try:
        bale("sendChatAction", {"chat_id": chat_id, "action": "typing"})
    except ERRORS:
        pass  # the typing indicator is a courtesy; it must never cost the answer
    question = text[:MAX_INPUT_CHARS]
    with lock:
        past = list(state["turns"])
    messages = [{"role": "system", "content": SYSTEM_PROMPT}, *past,
                {"role": "user", "content": question}]
    started = time.monotonic()
    try:
        answer = plain_text(ask_model(messages))
    except ERRORS as error:
        log("model_error", chat_id, kind=type(error).__name__)
        bale("sendMessage", {"chat_id": chat_id, "text": BUSY})
        return
    with lock:
        state["turns"].extend([{"role": "user", "content": question},
                               {"role": "assistant", "content": answer}])
    send_long(chat_id, answer)
    log("answered", chat_id, seconds=round(time.monotonic() - started, 1),
        chars_in=len(question), chars_out=len(answer))


def main():
    if not BALE_TOKEN or not LLM_MODEL:
        sys.exit("Set BALE_TOKEN and LLM_MODEL first.")
    print("Connected as", bale("getMe").get("username"))
    offset = None
    while True:
        params = {"timeout": 30}
        if offset is not None:
            params["offset"] = offset
        try:
            updates = bale("getUpdates", params, timeout=40)
        except ERRORS as error:
            log("poll_error", kind=type(error).__name__)
            time.sleep(5)
            continue
        for update in updates:
            offset = update["update_id"] + 1
            if "message" in update:
                try:
                    handle(update["message"])
                except Exception as error:  # one bad update must not stop the bot
                    log("handle_error", kind=type(error).__name__)


if __name__ == "__main__":
    main()

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

bash
export BALE_TOKEN='123456789:replace-with-your-token'
export LLM_MODEL='your-model-name'
# local model (default): LLM_BASE_URL=http://localhost:11434/v1
# provider instead:
# export LLM_BASE_URL='https://llm.example.ir/v1'
# export LLM_API_KEY='replace-with-your-key'
# optional, where /human requests go:
# export OPERATOR_CHAT_ID='staff-group-chat-id'
python3 bale_ai_bot.py

آنچه این کد اضافه کرده و دلیل هر کدام:

  • پرامپت سیستمی فارسی. دامنه پاسخ را به کار فروشگاه محدود می‌کند، می‌گوید وقتی مطمئن نیستی حدس نزن و هرگز اطلاعات حساس نخواه. این متن نمونه است؛ آن را با زبان و قواعد کسب‌وکار خودتان بازنویسی کنید. اصول نوشتن چنین دستوری در آموزش پرامپت نویسی آمده است.
  • حافظه کوتاه برای هر گفت‌وگو. شش رفت‌وبرگشت آخر هر گفت‌وگو در حافظه برنامه می‌ماند تا پرسش بعدی، مثل «پنجشنبه‌ها چطور؟»، معنا داشته باشد. فقط ۱۰۰۰ گفت‌وگویی که اخیراً فعال بوده‌اند نگه داشته می‌شوند و قدیمی‌ترین‌ها کنار می‌روند تا با زیاد شدن کاربران، حافظه سرور بی‌حد پر نشود. این حافظه با خاموش شدن برنامه پاک می‌شود و فرمان /reset هم آن را خالی می‌کند. این یک انتخاب آگاهانه برای حریم خصوصی است: گفت‌وگوها جایی نوشته نمی‌شوند.
  • خطای مدل. اگر مدل در ۱۲۰ ثانیه جواب ندهد، خطا برگرداند یا پاسخ خالی بدهد، کاربر پیام کوتاه «الان نمی‌توانم جواب بدهم» را می‌گیرد، نه سکوت.
  • خطای ۴۲۹ بله. اگر بله بگوید زیادی سریع فرستاده‌اید، کد به اندازه retry_after، و حداکثر ۳۰ ثانیه، صبر می‌کند و تا دو بار دوباره می‌فرستد؛ سقف ۳۰ ثانیه برای این است که یک پاسخ ۴۲۹ کل بازو را مدت طولانی متوقف نکند.
  • سقف پیام هر گفت‌وگو. کد از هر گفت‌وگو در هر دقیقه حداکثر شش پیام، از جمله فرمان‌ها، را می‌پذیرد. پیام هشدار فقط یک بار فرستاده می‌شود و پیام‌های اضافه بعدی بی‌پاسخ می‌مانند، تا خود بازو با جواب دادن به سیل پیام‌ها به سقف ارسال بله نخورد.
  • قالب‌بندی. متن هر پیام در بله به شکل Markdown خود بله نمایش داده می‌شود. صفحه قالب‌بندی متن پیام می‌گوید متن برجسته با یک ستاره در دو طرف ساخته می‌شود و ** پشتیبانی نمی‌شود. مدل‌ها معمولاً Markdown استاندارد می‌نویسند، پس تابع plain_text نشانه‌های اضافه را پاک می‌کند تا ستاره و # خام به کاربر نرسد.
  • پیام بلند. پاسخ‌های بلندتر از ۴۰۰۰ نویسه در چند پیام فرستاده می‌شوند تا از سقف ۴۰۹۶ نویسه رد نشوند. برش روی مرز بند، سطر یا واژه می‌افتد تا هیچ واژه‌ای وسط دو پیام نصف نشود.
  • وضعیت «در حال نوشتن». پیش از فراخوانی مدل، sendChatAction فرستاده می‌شود. این وضعیت حداکثر شش ثانیه دیده می‌شود؛ اگر مدل شما کندتر است، آن را هر پنج ثانیه تکرار کنید یا بپذیرید که کاربر مدتی چیزی نمی‌بیند. اگر فرستادن این وضعیت خطا بدهد، کد از آن می‌گذرد و جواب را همچنان می‌فرستد.

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

کیفیت فارسی مدل‌ها یکسان نیست و مدل‌های کوچک محلی گاهی جمله‌های خشک یا اشتباه دستوری می‌سازند. پیش از انتشار، ۳۰ تا ۵۰ پرسش واقعی از مشتریانتان جمع کنید و پاسخ چند مدل را روی همان‌ها مقایسه کنید.

پاسخ از اسناد سازمان خودتان

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

در کد بالا جای این کار دقیقاً پیش از ask_model است: قطعه‌های بازیابی‌شده را به عنوان یک پیام سیستمی دوم به فهرست messages اضافه کنید. جزئیات طراحی، ارزیابی کیفیت پاسخ فارسی و مسیر استقرار در راهنمای چت بات فارسی برای کسب‌وکار آمده و چرایی شکست بیشتر سامانه‌ها در لایه بازیابی را در انضباط بازیابی و کیفیت دانش نوشته‌ایم. یک هشدار امنیتی هم دارد: متن سندی که بازیابی می‌شود می‌تواند دستور پنهان داشته باشد. مدخل تزریق دستور در فهرست ده ریسک مدل‌های زبانی OWASP، با شناسه LLM01:2025، توضیح می‌دهد که تزریق غیرمستقیم وقتی رخ می‌دهد که مدل ورودی را از منبعی بیرونی مثل وب‌سایت یا فایل بگیرد؛ پس به بازوی پاسخ‌گو ابزاری ندهید که کاری انجام دهد.

وب‌هوک به‌جای getUpdates: کی و چطور

getUpdates فقط به اتصال خروجی از سرور شما به tapi.bale.ai نیاز دارد و بدون دامنه یا نشانی عمومی هم کار می‌کند؛ برای شروع و برای بازوهای کم‌کاربر بهترین انتخاب است. وب‌هوک وقتی می‌ارزد که کاربران زیاد شده‌اند و می‌خواهید چند پیام را هم‌زمان جواب دهید، یا برنامه شما از قبل یک سرویس وب با دامنه و گواهی معتبر است. در وب‌هوک، بله آپدیت را با درخواست HTTPS POST به نشانی شما می‌فرستد.

پرسش‌های متداول بله برای وب‌هوک پنج شرط می‌گذارد: داشتن گواهی SSL، یکی از درگاه‌های پشتیبانی‌شده، احتمال پشتیبانی نشدن گواهی‌های wildcard، پشتیبانی نشدن ریدایرکت، و یکی بودن CN گواهی با دامنه شما. چون فهرست درگاه‌ها در مستندات و پرسش‌های متداول فرق دارد، درگاه ۴۴۳ را به کار ببرید که در هر دو آمده است.

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

سریع جواب بدهید و بعد فکر کنید. مستندات بله درباره مهلت پاسخ وب‌هوک و رفتار تلاش دوباره چیزی نمی‌گوید، اما همان مستندات توضیح می‌دهد که update_id به‌خصوص در وب‌هوک برای نادیده گرفتن آپدیت‌های تکراری به کار می‌آید. پس فرض امن این است که یک آپدیت ممکن است بیش از یک بار برسد. کد زیر درخواست را بلافاصله با کد ۲۰۰ تأیید می‌کند، آپدیت را در صف می‌گذارد، چهار کارگر پس‌زمینه آن را با همان تابع handle جواب می‌دهند و شناسه‌های دیده‌شده را کنار می‌گذارد. آن را bale_webhook.py بنامید و کنار bale_ai_bot.py بگذارید:

Python
import hmac
import json
import os
import queue
import sys
import threading
from collections import deque
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

import bale_ai_bot as bot

SECRET = os.environ.get("WEBHOOK_SECRET", "")
PATH = f"/bale/{SECRET}"
WORKERS = 4

jobs = queue.Queue(maxsize=500)
seen_order = deque(maxlen=10_000)
seen = set()
seen_lock = threading.Lock()


def first_time(update_id):
    """Drop updates that Bale delivers more than once."""
    if not isinstance(update_id, int):
        return True
    with seen_lock:
        if update_id in seen:
            return False
        if len(seen_order) == seen_order.maxlen:
            seen.discard(seen_order[0])
        seen_order.append(update_id)
        seen.add(update_id)
        return True


class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        if not hmac.compare_digest(self.path.encode(), PATH.encode()):
            self.send_response(404)
            self.end_headers()
            return
        length = int(self.headers.get("Content-Length") or 0)
        if not 0 < length <= 1_000_000:
            self.send_response(413)
            self.end_headers()
            return
        try:
            update = json.loads(self.rfile.read(length))
            if not isinstance(update, dict):
                raise ValueError("not an update")
        except ValueError:
            self.send_response(400)
            self.end_headers()
            return
        self.send_response(200)  # acknowledge first, think later
        self.end_headers()
        try:
            jobs.put_nowait(update)
        except queue.Full:
            bot.log("queue_full")

    def log_message(self, format, *args):
        pass  # the default log line contains the path, and the path contains the secret


def worker():
    while True:
        update = jobs.get()
        try:
            if first_time(update.get("update_id")) and "message" in update:
                bot.handle(update["message"])
        except Exception as error:  # keep the worker alive whatever happens
            bot.log("handle_error", kind=type(error).__name__)
        finally:
            jobs.task_done()


def main():
    if len(SECRET) < 32 or not bot.BALE_TOKEN or not bot.LLM_MODEL:
        sys.exit("Set BALE_TOKEN, LLM_MODEL and a WEBHOOK_SECRET of 32+ characters.")
    for _ in range(WORKERS):
        threading.Thread(target=worker, daemon=True).start()
    ThreadingHTTPServer(("127.0.0.1", 8080), Handler).serve_forever()


if __name__ == "__main__":
    main()

این سرور فقط روی 127.0.0.1 گوش می‌دهد و باید پشت یک پراکسی معکوس با HTTPS قرار بگیرد. مستندات پایتون صریحاً می‌گوید ماژول http.server برای محیط تولید توصیه نمی‌شود و فقط بررسی‌های امنیتی پایه دارد؛ پس پراکسی، اندازه درخواست و TLS را کنترل کند و برای بار جدی‌تر کد را به یک چارچوب وب واقعی ببرید. راه‌اندازی Caddy یا Nginx با گواهی روی سرور ایرانی را در راهنمای نصب n8n روی سرور ایران گام‌به‌گام نوشته‌ایم و همان روش اینجا هم کار می‌کند. یک نکته ظریف هم در کد هست: تابع پیش‌فرض ثبت درخواست مسیر را در لاگ می‌نویسد و مسیر شامل راز است، پس خاموشش کرده‌ایم. پراکسی معکوس هم معمولاً مسیر هر درخواست را در لاگ دسترسی ثبت می‌کند؛ برای این مسیر لاگ را خاموش کنید یا بخش راز را در لاگ بپوشانید.

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

bash
export WEBHOOK_SECRET="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
python3 bale_webhook.py &
curl -sS "https://tapi.bale.ai/bot$BALE_TOKEN/setWebhook" \
  --data-urlencode "url=https://bot.example.ir/bale/$WEBHOOK_SECRET"
curl -sS "https://tapi.bale.ai/bot$BALE_TOKEN/getWebhookInfo"

پاسخ getWebhookInfo نشانی ثبت‌شده را نشان می‌دهد. اجرای پس‌زمینه با & فقط برای آزمایش است؛ در محیط تولید، WEBHOOK_SECRET را به فایل محیطی سرویس اضافه کنید و در واحد systemd بخش «محافظت از توکن» مسیر ExecStart را به bale_webhook.py تغییر دهید. برای برگشتن به getUpdates، متد deleteWebhook را صدا بزنید. دو نکته: کارگرها ممکن است دو پیام پشت‌سرهم یک کاربر را هم‌زمان جواب دهند؛ اگر ترتیب برایتان مهم است، تعداد کارگرها را یک بگذارید یا برای هر گفت‌وگو صف جدا بسازید. و اگر بازو روزی کاری فراتر از پاسخ متنی انجام داد، مثلاً سفارش ثبت کرد، حذف تکرار با update_id کافی نیست؛ چرایی‌اش را در امضای معتبر وب‌هوک، اجازه اجرای دوباره نیست توضیح داده‌ایم.

ساخت ربات بله با n8n

n8n گره داخلی برای بله ندارد؛ در کد گره‌های داخلی n8n گره‌ای به این نام پیدا نکردیم. سه راه باقی می‌ماند و فقط اولی را می‌توانیم با مستندات توجیه کنیم:

  1. گره‌های عمومی Webhook و HTTP Request. بله آپدیت را به یک Webhook می‌فرستد و پاسخ با یک درخواست HTTP به sendMessage برمی‌گردد. همه چیز مستند است و کد شخص ثالثی در کار نیست. راه پیشنهادی ما همین است.

  2. گره‌های تلگرام با نشانی پایه بله. اعتبارنامه تلگرام در n8n فیلدی به نام Base URL دارد؛ این را در کد منبع اعتبارنامه در نسخه 2.47.7 دیدیم، هرچند صفحه مستندات اعتبارنامه آن را نام نبرده است. پرسش‌های متداول بله هم می‌گوید راه انتقال ربات تلگرام به بله، عوض کردن این نشانی به https://tapi.bale.ai است. اما محرک تلگرام به کار نمی‌آید: کد گره Telegram Trigger در نسخه‌های فعلی این گره، یعنی بالاتر از نسخه ۱، هر درخواستی را که سرآیند راز مخصوص تلگرام را نداشته باشد با کد ۴۰۳ رد می‌کند و مستندات بله چنین سرآیندی را تعریف نکرده است. گره‌های ارسال تلگرام را هم روی بله آزمایش نکرده‌ایم.

  3. گره‌های جامعه (community nodes). جست‌وجوی «n8n-nodes-bale» در رجیستری npm در روز نگارش چند بسته از ناشران شخص ثالث نشان داد. یکی از آن‌ها در توضیحش خود را «رسمی» معرفی می‌کرد، اما نتوانستیم ارتباطش را با بله یا n8n تأیید کنیم. دوره‌های آموزشی بله ویدئویی درباره گره‌های جامعه دارد و از گره‌های balemessenger نام می‌برد، اما نام بسته npm آن‌ها را نمی‌دهد. مستند ریسک گره‌های جامعه در n8n هشدار می‌دهد این گره‌ها به کل ماشینی که n8n روی آن اجرا می‌شود و به داده ورکفلوهای شما دسترسی دارند. اگر یکی را انتخاب کردید، کدش را بخوانید و نسخه‌اش را ثابت کنید.

ورکفلو پیشنهادی چهار گره دارد:

  1. Webhook. روش POST. در Path یک رشته تصادفی طولانی بگذارید، مثلاً خروجی همان فرمان secrets.token_urlsafe در بخش قبل. Authentication را روی None بگذارید؛ مستند گره Webhook گزینه Header auth هم دارد، اما مستندات بله راهی برای فرستادن سرآیند دلخواه همراه وب‌هوک تعریف نکرده است و این گزینه پیام‌های بله را رد خواهد کرد. پس برخلاف توصیه عمومی برای وب‌هوک‌های عمومی، اینجا راز همان مسیر است. Respond را روی Immediately بگذارید تا بله بی‌درنگ پاسخ بگیرد.

  2. If. فقط گفت‌وگوهای خصوصی متنی را عبور دهید: شرط اول {{ $json.body.message.chat.type }} برابر private و شرط دوم وجود {{ $json.body.message.text }}.

  3. Basic LLM Chain. طبق مستند این گره، منبع پرامپت را Define below بگذارید و در Prompt (User Message) عبارت {{ $('Webhook').item.json.body.message.text }} را بنویسید. در بخش Chat Messages یک پیام از نوع System با پرامپت فارسی خودتان بسازید و بخواهید متن ساده و بی‌نشانه بنویسد. یک گره مدل گفت‌وگو هم وصل کنید: Ollama Chat Model برای مدل روی سرور خودتان، یا OpenAI Chat Model که در اعتبارنامه‌اش فیلد Base URL را به نشانی ارائه‌دهنده داخلی تغییر داده‌اید. هر دو تنظیم در راهنمای نصب n8n آمده است. خروجی این گره متن پاسخ را در فیلد text می‌دهد.

  4. HTTP Request. طبق مستند این گره: روش POST، نشانی https://tapi.bale.ai/bot<token>/sendMessage با توکن خودتان، Send Body روشن، Body Content Type روی JSON و Specify Body روی Using Fields Below. دو فیلد بسازید: chat_id با مقدار {{ $('Webhook').item.json.body.message.chat.id }} و text با مقدار {{ $json.text.slice(0, 4000) }}.

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

حافظه گفت‌وگو در n8n. مستند Basic LLM Chain از اتصال حافظه چیزی نمی‌گوید. برای حافظه، گره AI Agent را با زیرگره Simple Memory به کار ببرید و Session Key را برابر شناسه گفت‌وگو بگذارید. دو قید مستند دارد. اول، مستند AI Agent می‌گوید دست‌کم یک زیرگره ابزار باید به آن وصل باشد؛ چون بازوی پاسخ‌گو نباید ابزاری داشته باشد که کاری انجام دهد، ابزاری مثل Think Tool را وصل کنید که طبق مستندش فقط به ایجنت هوش مصنوعی فرصت می‌دهد پیش از پاسخ فکر کند. دوم، Simple Memory در حالت صف (queue mode) در ورکفلوی تولیدی کار نمی‌کند. طبق کد منبع n8n، AI Agent پاسخ را در فیلد output برمی‌گرداند، نه text؛ پس مقدار فیلد text در گره HTTP Request را به {{ $json.output.slice(0, 4000) }} تغییر دهید. این ترکیب را هم اجرا نکرده‌ایم. اصول طراحی ورکفلوی قابل اتکا، از تلاش دوباره تا مدیریت خطا، در آموزش n8n و ساخت ایجنت هوش مصنوعی آمده است.

ساخت ربات بله بدون کد نویسی و با گوشی

پاسخ صادقانه: بازوی هوش مصنوعی بدون هیچ برنامه‌نویسی ساخته نمی‌شود، اما سهم کد را می‌شود خیلی کم کرد. پرسش‌های متداول بله خودش می‌گوید ساخت بازو به مهارت برنامه‌نویسی نیاز دارد. نزدیک‌ترین مسیر به «بدون کد نویسی» همان n8n است و دوره‌های آموزشی خود بله هم این مسیر را No-Code می‌نامد و ساخت یک بازوی نوبت‌دهی پزشکی با آن را آموزش می‌دهد. با این حال حتی در n8n باید یک سرور همیشه روشن، دامنه با HTTPS و چند عبارت مثل {{ $json.body.message.text }} را مدیریت کنید.

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

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

ساخت ربات بله با PHP و C#

چون API فقط HTTP و JSON است، با هر زبانی تنها کلاینت HTTP عوض می‌شود. در PHP، بدنه وب‌هوک از php://input خوانده می‌شود و پاسخ با cURL برمی‌گردد. این نمونه کمینه راز را از پارامتر key نشانی می‌خواند و پیام را پژواک می‌کند. آن را با php -l بررسی کردیم و با سرور داخلی PHP روی همان شبیه‌ساز محلی اجرا کردیم:

PHP
<?php
// Bale webhook in plain PHP: check the secret, then echo the text back.
$token = getenv('BALE_TOKEN');
$secret = getenv('WEBHOOK_SECRET');
$key = $_GET['key'] ?? '';

if (!is_string($secret) || strlen($secret) < 32 || !is_string($key) || !hash_equals($secret, $key)) {
    http_response_code(404);
    exit;
}

$update = json_decode(file_get_contents('php://input'), true);
$chatId = $update['message']['chat']['id'] ?? null;
$text = $update['message']['text'] ?? null;
http_response_code(200);

if ($chatId !== null && is_string($text)) {
    $ch = curl_init("https://tapi.bale.ai/bot{$token}/sendMessage");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode(['chat_id' => $chatId, 'text' => $text], JSON_UNESCAPED_UNICODE),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
    ]);
    curl_exec($ch);
}

نشانی وب‌هوک در این حالت چیزی مثل https://bot.example.ir/webhook.php?key=... است و چون وب‌سرور نشانی کامل درخواست‌ها را در لاگ دسترسی می‌نویسد، راز را آنجا هم بپوشانید. گزینه JSON_UNESCAPED_UNICODE لازم نیست اما متن فارسی را در لاگ‌ها خواناتر نگه می‌دارد. PHP پاسخ ۲۰۰ را وقتی اجرای فایل تمام شود می‌فرستد، یعنی پس از فراخوانی cURL؛ برای پژواک اشکالی ندارد، اما اگر خواستید مدل زبانی را از PHP صدا بزنید، کار را در صف بگذارید تا بله پشت پاسخ مدل منتظر نماند. در سی‌شارپ، یک HttpClient با BaseAddress برابر https://tapi.bale.ai/bot<token>/ بسازید، دقت کنید که اسلش پایانی حذف نشود، و با PostAsJsonAsync به sendMessage بفرستید. نام فیلدها باید دقیقاً chat_id و text باشد؛ پس یا شیء ناشناس با همین نام‌ها بسازید یا روی ویژگی‌های کلاس JsonPropertyName بگذارید. برای وب‌هوک هم یک endpoint از نوع POST در ASP.NET Core کافی است که بدنه را بخواند، راز مسیر را مقایسه کند و فوراً ۲۰۰ برگرداند.

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

پیش از کاربر واقعی: هزینه، قوانین و امنیت

واگذاری به انسان

دستیار خودکار باید راهی روشن به انسان داشته باشد. در کد بالا، فرمان /human نام کاربر، نام کاربری‌اش اگر داشته باشد و شناسه گفت‌وگو را به یک گروه کاری می‌فرستد که شناسه‌اش در OPERATOR_CHAT_ID آمده است. نام را خود کاربر انتخاب کرده، پس کد پیش از فرستادن، نشانه‌های قالب‌بندی را از آن پاک می‌کند. بازو باید عضو آن گروه باشد. برای پیدا کردن شناسه گروه، برنامه را متوقف کنید، در گروه نام بازو را تگ کنید و chat.id همان پیام را در خروجی getUpdates ببینید؛ این مراحل را از مستندات و پرسش‌های متداول بله درآورده‌ایم و روی بله واقعی اجرا نکرده‌ایم. همکار شما می‌تواند با نام کاربری به کاربر پیام بدهد، یا اگر کاربر نام کاربری ندارد، از طرف بازو و با همان sendMessage و شناسه گفت‌وگو جواب بدهد. کاربر پیام تأیید می‌گیرد؛ اگر OPERATOR_CHAT_ID را تنظیم نکرده باشید یا فرستادن به گروه شکست بخورد، بازو به جای وعده دادن، می‌گوید که همکار انسانی وصل نیست و رویداد handoff_failed در لاگ ثبت می‌شود. ساعت پاسخ‌گویی را در پیام تأیید بنویسید و موضوع‌هایی را که همیشه باید به انسان برسند، مثل شکایت، بازپرداخت و هر چیز حقوقی، در پرامپت سیستمی نام ببرید.

محدودیت‌ها و هزینه پیام

برای API معمولی بازو، مستندات بله هزینه‌ای فهرست نکرده است. در این API ظرفیت ارسال هر بازو بر پایه تعامل کاربران با آن در گفت‌وگوهای خصوصی محاسبه می‌شود. اگر بخواهید به کاربرانی که قبلاً بازو را راه انداخته‌اند بیرون از گفت‌وگوی جاری پیام بدهید یا اطلاع‌رسانی انبوه کنید، مستندات بله «API کسب‌وکاری» را معرفی می‌کند. نشانی آن همان نشانی معمولی با بخش اضافه business است، یعنی https://tapi.bale.ai/business/bot<TOKEN>/<METHOD_NAME>، و سهمیه نرخ جدا و بالاتری دارد. فعلاً فقط getMe، sendMessage، forwardMessage، sendPhoto، sendVideo، sendAudio و sendDocument را پشتیبانی می‌کند، فقط به گفت‌وگوهای خصوصی می‌فرستد و فایل را فقط با file_id می‌پذیرد. هزینه هر پیام خودکار از اعتبار حساب کسب‌وکاری که در پنل کسب‌وکار بله شارژ شده کم می‌شود. مبلغ هر پیام را در مستندات عمومی پیدا نکردیم.

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

هزینه مدل را هم جدا حساب کنید. مدل روی سخت‌افزار خودتان هزینه ثابت سخت‌افزار، برق و نگهداری دارد و ارائه‌دهنده معمولاً به ازای توکن پول می‌گیرد. سقف شش پیام در دقیقه برای هر گفت‌وگو و بریدن پیام‌های بلندتر از ۱۵۰۰ نویسه در کد بالا، جلوی بزرگ شدن ناگهانی صورت‌حساب را هم می‌گیرد.

ثبت رویداد بدون نگهداری داده حساس

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

محافظت از توکن

توکن و کلید مدل را در یک فایل محیطی نگه دارید که فقط root و کاربر سرویس بتوانند آن را بخوانند، و برنامه را با همین کاربر کم‌دسترسی و با systemd اجرا کنید تا پس از خطا یا راه‌اندازی دوباره سرور خودکار بالا بیاید:

INI
# /etc/systemd/system/bale-bot.service
[Unit]
Description=Bale AI bot
After=network-online.target
Wants=network-online.target

[Service]
User=balebot
WorkingDirectory=/opt/balebot
EnvironmentFile=/etc/balebot.env
Environment=PYTHONUNBUFFERED=1
ExecStart=/usr/bin/python3 /opt/balebot/bale_ai_bot.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

فایل /etc/balebot.env همان متغیرهای BALE_TOKEN، LLM_MODEL و در صورت نیاز LLM_BASE_URL، LLM_API_KEY و OPERATOR_CHAT_ID را دارد، هر کدام در یک سطر و در قالب NAME=value. سپس کاربر سرویس را بسازید، فایل‌های برنامه را سر جایشان بگذارید و سرویس را فعال کنید:

bash
sudo useradd --system --no-create-home --shell /usr/sbin/nologin balebot
sudo mkdir -p /opt/balebot
sudo cp bale_ai_bot.py bale_webhook.py /opt/balebot/
sudo chown root:balebot /etc/balebot.env
sudo chmod 640 /etc/balebot.env
sudo systemctl daemon-reload
sudo systemctl enable --now bale-bot
journalctl -u bale-bot -f

فرمان آخر گزارش‌های برنامه را زنده نشان می‌دهد. توکن داخل نشانی هر درخواست است، پس نشانی‌های کامل درخواست‌ها را در لاگ چاپ نکنید. یک محدودیت این روش را هم بدانید: مستند systemd.exec می‌گوید متغیرهای محیطی برای رازها مناسب نیستند، چون ممکن است از راه D-Bus به کاربران کم‌دسترسی نشان داده شوند و به فرایندهای فرزند هم برسند، و برای این کار LoadCredential= را پیشنهاد می‌کند. ما برای سادگی فایل محیطی را نگه داشته‌ایم؛ روی سروری که چند نفر به آن دسترسی دارند، آن روش را در نظر بگیرید.

سوءاستفاده و محدودیت نرخ

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

اعلام صریح ماشین بودن

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

قوانین بله برای بازوها

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

میزبانی داخل ایران و قطع اینترنت بین‌الملل

مسیر هر پاسخ چهار حلقه دارد: کاربر، سرور بله، سرور برنامه شما و مدل زبانی. اگر برنامه و مدل هر دو روی سروری داخل ایران اجرا شوند، بخشی از زنجیره که در اختیار شماست به اینترنت بین‌الملل وابسته نیست. اگر برنامه در ایران باشد اما مدل را از سرویسی خارجی صدا بزند، هر پاسخ به همان اتصال بین‌المللی گره خورده است و با قطع آن، بازو فقط می‌تواند پیام «الان نمی‌توانم جواب بدهم» بفرستد. همین درباره سرویس داخلی‌ای صدق می‌کند که درخواست شما را به مدلی خارجی بازارسال می‌کند. این یک پیامد طراحی است، نه پیش‌بینی. گزارش اختلال‌های اینترنت در سه‌ماهه نخست ۲۰۲۶ کلادفلر می‌گوید ترافیکی که این شرکت از ایران می‌دید از ۱۸ دی ۱۴۰۴ (۸ ژانویه ۲۰۲۶) تا ۱ بهمن (۲۱ ژانویه) نزدیک صفر ماند و از ۹ اسفند ۱۴۰۴ (۲۸ فوریه ۲۰۲۶) دوباره به کمتر از یک درصد سطح پیشین افتاد.

جهت ارتباط هم مهم است. در getUpdates سرور شما باید به tapi.bale.ai برسد؛ در وب‌هوک، سرور بله باید به سرور شما برسد. اگر سرور برنامه بیرون از ایران باشد، در هر دو حالت به اتصال بین‌المللی وابسته‌اید. اینکه خود بله در چنین شرایطی در دسترس می‌ماند یا نه، به زیرساخت بله بستگی دارد و ما درباره‌اش ادعایی نمی‌کنیم.

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

خطاهای رایج ربات بله و راه‌حل

نشانهعلت محتملراه‌حل
getMe خطای 401 و Unauthorized می‌دهدتوکن نادرست، ناقص کپی‌شده یا باطل‌شدهتوکن را دوباره از بازوی پدر بگیرید و بدون فاصله اضافه کپی کنید
getUpdates پیامی برنمی‌گرداند یا خطا می‌دهدوب‌هوک تنظیم شده یا برنامه دیگری هم آپدیت می‌گیردgetWebhookInfo را ببینید، deleteWebhook را صدا بزنید و فقط یک نسخه برنامه اجرا کنید
همان پیام‌ها مدام تکرار می‌شوندoffset جلو نمی‌رودoffset را برابر update_id آخر به‌علاوه یک بفرستید
وب‌هوک ثبت شده اما چیزی نمی‌رسدگواهی نامعتبر، درگاه نامناسب، ریدایرکت یا CN متفاوتگواهی معتبر روی همان دامنه، درگاه ۴۴۳ و بدون ریدایرکت
خطای 429ارسال سریع‌تر از حد مجازبه اندازه retry_after صبر کنید و ارسال انبوه را در چند ساعت پخش کنید
پیام بلند فرستاده نمی‌شودمتن بیش از ۴۰۹۶ نویسهپیام را تکه‌تکه بفرستید
ستاره و # خام در پاسخ دیده می‌شودقالب‌بندی Markdown بله با Markdown استاندارد فرق داردخروجی مدل را پیش از ارسال پاک کنید و در پرامپت متن ساده بخواهید
بازو در گروه جواب نمی‌دهدتنظیم حریم خصوصی بازو یا کد که فقط گفت‌وگوی خصوصی را جواب می‌دهددر گروه نام بازو را تگ کنید یا منطق گروه را جدا بنویسید؛ بازوها پیام بازوهای دیگر را نمی‌بینند
دکمه شیشه‌ای در حالت انتظار می‌ماندanswerCallbackQuery صدا زده نشدهپس از هر فشردن دکمه این متد را صدا بزنید
مدل خطای اتصال می‌دهدسرور مدل خاموش است، یا برنامه در Docker اجرا می‌شود و localhost به خود همان کانتینر اشاره می‌کند، نه به کانتینر مدلLLM_BASE_URL را بررسی کنید و در Docker نام سرویس مدل را به کار ببرید
/human می‌گوید همکار انسانی وصل نیستOPERATOR_CHAT_ID تنظیم نشده، شناسه گروه نادرست است یا بازو عضو گروه نیستشناسه گروه را بررسی کنید، بازو را به گروه اضافه کنید و برنامه را دوباره اجرا کنید؛ رویداد handoff_failed در لاگ یعنی فرستادن به گروه شکست خورده است
پاسخ‌ها انگلیسی یا فارسی شکسته‌اندمدل برای فارسی ضعیف است یا پرامپت روشن نیستمدل دیگری را با پرسش‌های واقعی بیازمایید و زبان پاسخ را در پرامپت صریح کنید
محرک تلگرام در n8n کد ۴۰۳ می‌دهداین گره سرآیند راز تلگرام را می‌خواهدگره عمومی Webhook را به کار ببرید
پیام‌های زمان خاموشی برنامه از دست رفته‌اندبله فقط ۲۰۰۰ آپدیت آخر را تا ۲۴ ساعت نگه می‌داردبرنامه را با systemd یا ابزار مشابه همیشه روشن نگه دارید

پرسش‌های رایج

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

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

چطور ربات تلگرام را به بله منتقل کنم؟

پرسش‌های متداول بله می‌گوید یک بازوی تازه در بله بسازید، توکن آن را به کار ببرید و نشانی سرور را در کد یا کتابخانه به https://tapi.bale.ai تغییر دهید. همه متدهای تلگرام در بله نیست، پس هر قابلیت را جداگانه بیازمایید.

آیا می‌شود ربات بله را به چت جی پی تی (ChatGPT) وصل کرد؟

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

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

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

ربات بله می‌تواند پیام صوتی را بفهمد؟

پیام صوتی به شکل یک فایل با file_id می‌رسد و بازو می‌تواند آن را با getFile تا ۲۰ مگابایت دانلود کند. برای فهمیدنش باید آن را به متن تبدیل کنید و بعد به مدل بدهید؛ گزینه‌ها و دقت آن‌ها در فارسی را در راهنمای تبدیل صوت به متن فارسی بررسی کرده‌ایم.

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

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

یادداشت منابع

این راهنما در ۲۵ آبان ۱۴۰۵ (۱۶ نوامبر ۲۰۲۶) با صفحه‌های رسمی زیر بازبینی شد. کدهای پایتون را با python3 -m py_compile و کد PHP را با php -l بررسی کردیم و همه را روی یک شبیه‌ساز محلی از پاسخ‌های مستند API بله و یک سرور مدل ساختگی اجرا کردیم، از جمله با خطای ۴۲۹، پاسخ نامعتبر، آپدیت تکراری و پیام‌های هم‌زمان. در همان روز یک بازوی آزمایشی واقعی هم در بله ساختیم و bale_ai_bot.py را با getUpdates روی آن اجرا کردیم: getMe، پاسخ ۴۰۱ برای توکن نادرست، setMyCommands، /start، یک پرسش، یک پاسخ بلند چندپیامی، /reset و /human. در این آزمایش مدل زبانی ساختگی بود و وب‌هوک و کد PHP روی بازوی واقعی اجرا نشدند. ورکفلوی n8n را از روی مستندات و کد منبع n8n نوشته‌ایم و اجرا نکرده‌ایم. متن گفت‌وگوی بازوی پدر در مستندات نوشتاری بله نیامده و آن را از همان آزمایش نقل کرده‌ایم. مهلت پاسخ و رفتار تلاش دوباره وب‌هوک و قیمت پیام‌های کسب‌وکاری در منابع عمومی بله نیامده بود و حدس نزده‌ایم.

برچسب‌هاربات بلهبازوی بلهساخت ربات بلهچت بات هوش مصنوعیپایتونn8nوب‌هوک

مطالب مرتبط

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

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