ربات بله بساز.
بدون محدودیت.
فریمورک همه کاره، async و AI-Native برای بله. از کسی که کد بلد نیست تا مهندسی که به RPC خام نیاز دارد — سه لایه دسترسی، همه باز.
نصب
Python 3.9 یا بالاتر. بدون وابستگی سنگین.
# از PyPI
pip install badking
# یا با uv (سریعتر)
uv pip install badking
# یا آخرین نسخه توسعه
pip install git+https://github.com/badking-daniyal/badking.git
python examples/echo_bot.py --mock — ربات را در حالت شبیهسازی اجرا میکند، بدون نیاز به @botfather.
شروع در ۵ دقیقه
توکن را از @botfather در بله بگیر. بدون لاگین شماره، بدون session file.
import asyncio
from badking import Bot, Dispatcher, F
bot = Bot("123456789:TOKEN_FROM_BOTFATHER")
dp = Dispatcher()
@dp.message(F.text == "/start")
async def start(message, bot):
await bot.send_message(message.chat.id, "خوش آمدی! 🚀")
@dp.message(F.text)
async def echo(message, bot):
await bot.send_message(message.chat.id, f"شما گفتید: {message.text}")
asyncio.run(bot.polling(dp))
همین. پارامتر bot خودکار تزریق میشود — لازم نیست دستی پاس بدهی.
نمونههای واقعی
هر نمونه کد کامل و قابل اجراست، نه شبهکد.
۱. ویزارد چندمرحلهای
پرسشوپاسخ خطی بدون دستوپنجه نرم کردن با FSM:
from badking import Bot, Dispatcher, F, ConversationManager
bot = Bot("TOKEN")
dp = Dispatcher()
convos = ConversationManager()
dp.register_middleware(convos)
@dp.message(F.text == "/register")
async def register(message, bot):
async with convos.conversation(bot, message.chat.id) as conv:
await conv.send("اسم کاملت چیه؟")
name = await conv.get_response(timeout=60)
await conv.send("شماره تماس؟")
phone = await conv.get_response(timeout=60)
await conv.send(f"ثبت شد ✅\nنام: {name.text}\nتلفن: {phone.text}")
اگر کاربر جواب ندهد ConversationTimeout میگیری. اگر چت دیگری پیام بدهد، مزاحم مکالمه نمیشود.
۲. منوی چندصفحهای
from badking import KeyboardPaginator, F
products = ["کتاب پایتون", "هدفون", "ماوس", "کیبورد", "مانیتور"]
paginator = KeyboardPaginator(products, per_page=3, prefix="shop")
@dp.message(F.text == "/shop")
async def shop(message, bot):
await bot.send_message(
message.chat.id, "محصولی انتخاب کن:",
reply_markup=paginator.markup(page=0).model_dump(exclude_none=True),
)
@dp.callback_query(F.data.startswith("shop:"))
async def on_shop(cq, bot):
parsed = paginator.parse(cq.data)
if not parsed:
return
kind, value = parsed
if kind == "page":
await bot.edit_message_text(
cq.message.chat.id, cq.message.message_id, "محصولی انتخاب کن:",
reply_markup=paginator.markup(page=value).model_dump(exclude_none=True),
)
elif kind == "item":
await bot.answer_callback_query(cq.id, f"انتخاب شد: {products[value]}")
دکمههای «قبلی / بعدی» و شماره صفحه خودکار ساخته میشوند.
۳. FSM پایدار با SQLite
from badking import Bot, Dispatcher, F, State, StatesGroup, SQLiteStorage
class Order(StatesGroup):
item = State()
address = State()
dp = Dispatcher(storage=SQLiteStorage("orders.db"))
bot = Bot("TOKEN")
@dp.message(F.text == "/order")
async def start_order(message, state):
await state.set_state(Order.item)
await bot.send_message(message.chat.id, "چه چیزی میخواهی؟")
@dp.message(Order.item)
async def get_item(message, state):
await state.update_data(item=message.text)
await state.set_state(Order.address)
await bot.send_message(message.chat.id, "آدرس تحویل؟")
@dp.message(Order.address)
async def get_address(message, state):
data = await state.get_data()
await state.clear()
await bot.send_message(
message.chat.id,
f"سفارش ثبت شد ✅\nکالا: {data['item']}\nآدرس: {message.text}",
)
ربات را ریاستارت کن — state سر جایش است.
۴. دستیار هوشمند با ابزار
from badking import AIAssistant, OpenAICompatibleLLM
llm = OpenAICompatibleLLM(
base_url="https://api.openai.com/v1",
api_key="sk-...",
model="gpt-4o-mini",
)
assistant = AIAssistant(
llm,
persona="دستیار فروشگاه، مودب و کوتاه جواب بده",
tools=[check_order_status, get_price],
)
answer = await assistant.reply(user_key=str(message.from_user.id), text=message.text)
await bot.send_message(message.chat.id, answer)
مدل خودش تصمیم میگیرد کدام ابزار را صدا بزند. اگر ابزار خطا بدهد، کل مکالمه نمیشکند.
۵. RAG روی مستندات خودت
from badking import SimpleRAG, AIAssistant, OpenAICompatibleLLM
rag = SimpleRAG()
rag.add_text(open("faq.txt", encoding="utf-8").read(), source="faq")
rag.add_text(open("policies.txt", encoding="utf-8").read(), source="policies")
assistant = AIAssistant(OpenAICompatibleLLM(...), rag=rag)
ربات از محتوای فایلهای تو جواب میدهد، نه از خودش.
۶. اتصال به هر سرویس خارجی
from badking import Connector, Auth
zarinpal = Connector(
base_url="https://api.zarinpal.com",
auth=Auth(type="bearer", token="..."),
retries=3,
)
result = await zarinpal.post("/pg/v4/payment/request.json", json_body={
"merchant_id": "....",
"amount": 50000,
"callback_url": "https://example.com/callback",
})
Retry خودکار روی 5xx و 429، با احترام به Retry-After.
۷. پرداخت داخل بله
from badking import PaymentToolkit
pay = PaymentToolkit(bot)
await pay.send_invoice(
chat_id=message.chat.id,
title="کتاب پایتون",
description="نسخه چاپی، ارسال رایگان",
payload="order-1234",
provider_token="...",
prices=[{"label": "کتاب", "amount": 500000}],
)
۸. مینیاپ با اعتبارسنجی امن
from badking import validate_init_data
# در سرور مینیاپ، initData را از کلاینت بگیر
data = validate_init_data(init_data_from_client, bot_token="123456:ABC...")
print(data.user.id, data.user.first_name) # امضا تأیید شد
الگوریتم دقیقاً مطابق مستندات رسمی بله: فیلدها الفبایی مرتب، با \n متصل، HMAC-SHA256.
سه لایه دسترسی
هر لایه برای یک مخاطب. لایه پایینتر همیشه باز است.
| لایه | مخاطب | ابزار |
|---|---|---|
| ۰ — بدون کد | صاحب کسبوکار | Flow Builder، CLI، dry-run |
| ۱ — پایتون | برنامهنویس | Dispatcher، FSM، Filter، AI، Connector، Conversation |
| ۲ — خام | مهندس | bot.request("anyMethod", {...}) — هر متد، هر JSON |
ربات بدون نوشتن کد
برای کسی که پایتون نمیداند ولی ربات میخواهد.
badking new mybot # ساخت پروژه کامل
badking dry-run # تست جریان بدون توکن
badking codegen # تبدیل flow.json به کد پایتون
badking setup # تنظیم توکن
badking run # اجرا
flow.json را با Notepad ویرایش کن:
{
"start": "welcome",
"steps": {
"welcome": {"type": "message", "text": "سلام! 👋", "next": "ask_name"},
"ask_name": {"type": "ask", "text": "اسمت چیه؟", "save": "name", "next": "done"},
"done": {"type": "message", "text": "خوش آمدی {name}!"}
}
}
بدون یک خط پایتون، یک ربات مکالمهای داری. وقتی بزرگ شد، badking codegen همان جریان را به کد تبدیل میکند.
مقایسه با aiobale
صادقانه، بدون اغراق.
| قابلیت | aiobale | BADKING |
|---|---|---|
| توکن رسمی @botfather | ✗ | ✓ |
| Self-bot / Internal API | ✓ | ✓ ایزوله، پیشفرض خاموش |
| FSM + SQLite | ✓ | ✓ |
| Conversation (ویزارد) | ✓ | ✓ |
| KeyboardPaginator | ✓ | ✓ |
| Magic Filter F | ✓ | ✓ |
| Middleware + Rate Limit | ✓ | ✓ |
| Webhook Server | ✓ | ✓ |
| MiniApp + HMAC | ✗ | ✓ |
| سفیر (OTP، قالب) | ✗ | ✓ |
| پرداخت فاکتور رسمی | ✗ | ✓ |
| Business API | ✗ | ✓ |
| AI: Tool Calling + RAG | ✗ | ✓ |
| بدونکد (Flow Builder) | ✗ | ✓ |
| Connector به هر API | ✗ | ✓ |
| Observability (Prometheus) | ✗ | ✓ |
| Docker + CI آماده | ✗ | ✓ |
| مستندات فارسی | ✗ | ✓ |
ساختار پروژه
۷۶ ماژول، هر کدام یک مسئولیت.
badking/
├── core/ Bot، Dispatcher، Router، خطاها
├── types/ مدلهای Pydantic
├── filters/ Magic Filter F
├── fsm/ State، StatesGroup، FSMContext
├── storage/ Memory، SQLite
├── conversation/ ویزارد پرسشوپاسخ
├── keyboards/ KeyboardPaginator
├── miniapp/ اعتبارسنجی HMAC initData
├── safir/ سرویس سفیر (OTP، قالب)
├── payments/ فاکتور و پرداخت
├── business/ Business API
├── ai/ LLM، حافظه، RAG، دستیار
├── flows/ Flow Builder بدون کد
├── connectors/ HTTP به هر سرویس
├── jobs/ Scheduler، JobQueue
├── events/ Event Bus
├── orm/ Store
├── media/ Voice، OCR
├── observability/ Metrics، لاگ JSON
├── security/ AntiSpam، AuditLog، RBAC، Secrets
├── testing/ DryBot، Health
├── middleware/ logging، metrics، antispam
├── ratelimit/ Rate Limiter با اولویت
├── recovery/ Offset Store اتمیک
├── adapters/ Multi-platform
├── compat/ سازگاری aiogram/PTB
└── hybrid/ Self-bot (ایزوله، پیشفرض خاموش)
مرز صادقانه
اینها را باید بدانی، نه اینکه بعداً کشف کنی.
تاریخچه پیامها
iter_messages ما آپدیتهای موجود را میپیماید. تاریخچه کامل و قدیمیتر از ۲۴ ساعت با توکن رسمی ممکن نیست — برای آن لایه hybrid لازم است.
ریسک self-bot
لایه hybrid پیشفرض خاموش است و بدون ack_risk=True فعال نمیشود. دلیلش: Internal API غیررسمی است، میشکند، و میتواند اکانت شخصیات را ببندد.
اعداد تأییدنشده
اعدادی مثل «۴۰۹۶ کاراکتر» یا «حذف تا ۴۸ ساعت» در مستندات رسمی بله نیامدهاند. در BADKING پیشفرض قابلتنظیماند و از retry_after واقعی سرور یاد میگیرند.
RPC داخلی self-bot
پیادهسازی کامل ۸۰+ متد RPC داخلی هنوز انجام نشده. رابط و ایزولاسیون آماده است؛ خود RPC بهعنوان پلاگین جداگانه منتشر میشود.
بیشتر
مستندات بله
خلاصه مستندات رسمی API بله، با نکات عملی.
نقشه راه
وضعیت فازها و آنچه در نسخههای بعدی میآید.
هشدار self-bot
چرا لایه hybrid ایزوله است و چه ریسکی دارد.
شروع سریع
راهنمای قدمبهقدم فارسی برای اولین ربات.