فهرست مطالب ۱۰ بخش
- ساخت بازوی هوش مصنوعی در بله: مهارت چه چیزی یاد میدهد؟
- ساخت ربات بله با پایتون یا PHP
- بازوی هوش مصنوعی: پیام بلند، نشانگر تایپ و حافظه
- مینیاپ بله و اعتبارسنجی initData
- پرداخت در بازوی بله با بله پی
- یک جلسه کار با این مهارت چه شکلی دارد؟
- نصب مهارت بله در Claude Code، Codex و Cursor
- قبل از اجرای کد بازو روی سرور
- بعد از ساخت بازو: دستیار خودتان هم در بله پیام بدهد
- سؤال‌های پرتکرار
می‌خواهید در بله بازویی داشته باشید که سؤال مشتری‌ها را با ChatGPT یا Claude جواب بدهد، یا مینی‌اپی که داخل بله باز شود و پول بگیرد. از دستیار برنامهنویسی کد می‌خواهید و جوابی می‌گیرید که بوی تلگرام میدهد: نشانی API تلگرام، پرداختی که در بله وجود ندارد، یا حدس‌هایی دربارهٔ اینکه بله کجا فرق دارد.
برای ساخت بازوی هوش مصنوعی در بله باید بازوی خودتان را بسازید: توکن را از @botfather در بله می‌گیرید، کد را روی سرور خودتان اجرا می‌کنید و کلید API مدل زبانی را هم خودتان می‌دهید. مهارت «ساخت بات و مینیاپ بله» (Bale Bot Skills) کمک میکند دستیار برنامهنویسی، مثل Claude Code، Codex یا Cursor، این کد را با قواعد خود بله بنویسد، نه با حدس از روی تلگرام. پس جواب کوتاه به «نصب هوش مصنوعی در بله» این است که هوش مصنوعی را نصب نمی‌کنید، بازویش را می‌سازید.
ساخت بازوی هوش مصنوعی در بله: مهارت چه چیزی یاد میدهد؟
مستندات رسمی بله می‌گوید API بازو «بر پایهٔ API بات تلگرام و با اعمال تغییراتی جزئی» طراحی شده است. دستیار تلگرام را خوب می‌شناسد و همین شباهت باعث میشود تفاوت‌ها را نبیند. مخزن این مهارت که یک توسعه‌دهندهٔ مستقل (تقی مولوی) نوشته، چهار مهارت دارد:
| مهارت | برای چه کاری |
|---|---|
bale-bot-development |
بازوی معمولی: وب‌هوک، کیبورد، ماشین حالت، عضویت اجباری در کانال، بله پی |
bale-miniapp-development |
مینیاپ: SDK بله، اعتبارسنجی initData، مسیریابی و CSP |
bale-ai-bot |
بازوی هوش مصنوعی با OpenAI، Claude، Gemini، DeepSeek و Ollama |
using-bale-skills |
راهنمای انتخاب: به دستیار می‌گوید برای هر کار کدام سه‌تای بالا را بخواند |
کنار مهارت‌ها قالب کد آماده هم هست: PHP با MySQL، پایتون (long polling با httpx، وب‌هوک FastAPI و یک بازوی گفتگو با OpenAI)، Node.js با TypeScript و Express، و یک مینیاپ React با Vite.
ساخت ربات بله با پایتون یا PHP
مهارت پایه نشانی‌های درست را به دستیار میدهد: درخواست‌ها به https://tapi.bale.ai/bot<token>/<method> می‌روند و فایل‌ها از https://tapi.bale.ai/file/bot<token>/<file_id> دانلود می‌شوند. بازو را هم داخل خود بله با @botfather می‌سازید. چند نکته از این مهارت که دستیار بدون آن معمولاً از قلم می‌اندازد:
- شبکهٔ سرورهای ایران: مهارت می‌گوید روی هاست‌های داخل ایران، اتصال IPv6 و HTTP/2 به سرور بله گاهی گیر میکند. برای همین IPv4 و HTTP/1.1 را اجباری میکند و مهلت اتصال را ۱۵ ثانیه و مهلت کل را ۳۰ ثانیه می‌گذارد.
- عضویت اجباری در کانال: نام کاربری کانال باید با حروف کوچک نوشته شود و بازو باید ادمین کانال باشد، وگرنه
getChatMemberخطای ۴۰۴ برمی‌گرداند. - آلبوم عکس: چند عکسی که با هم فرستاده می‌شوند یک
media_group_idمشترک دارند. مهارت پیشنهاد میکند ۲ تا ۳ ثانیه صبر کنید و همه را با هم پردازش کنید. - حالت کاربر: برای گفتگوهای چندمرحله‌ای جدول
usersبا ستونstepدر MySQL، و خواندن امن ورودی وب‌هوک در PHP.
بازوی هوش مصنوعی: پیام بلند، نشانگر تایپ و حافظه
جواب مدل زبانی اغلب از سقف پیام بله بلندتر است. طبق مهارت bale-ai-bot، هر پیام بله حداکثر ۴۰۹۶ نویسه است و نمونه‌کدش جواب را در تکه‌های ۴۰۰۰ نویسه‌ای می‌فرستد. بقیهٔ چیزهایی که دستیار از این مهارت یاد می‌گیرد:
- تا مدل فکر میکند، با
sendChatActionنشانگر «در حال نوشتن» نشان داده شود. - ستاره و بک‌تیکِ جفت‌نشده در جواب مدل پاک شود تا قالب پیام به‌هم نریزد.
- جواب تدریجی با ویرایش همان پیام (
editMessageText) شبیه‌سازی شود، با فاصلهٔ دست‌کم ۱٫۸ ثانیه بین ویرایش‌ها. - فقط چند نوبت آخر گفتگو در SQLite یا Redis نگه داشته شود تا هزینهٔ توکن بالا نرود.
نمونه‌کد خود مهارت FastAPI و کتابخانهٔ OpenAI است و کلید را از OPENAI_API_KEY میخواند. کلید هر سرویسی که انتخاب کنید و هزینه‌اش با خودتان است.
مینیاپ بله و اعتبارسنجی initData
مینیاپ یک صفحهٔ وب است که داخل بله باز میشود. مهارت bale-miniapp-development اسکریپت SDK را در <head> می‌گذارد و با window.Bale.WebApp کار میکند: ready() و expand() برای شروع، sendData() برای فرستادن داده به بازو (تا ۴ کیلوبایت)، openInvoice برای پرداخت، showScanQrPopup برای اسکن QR و BackButton برای دکمهٔ برگشت. رنگ‌ها هم از themeParams بله گرفته میشود.
دو نکته‌اش جای خطای رایج است:
- دکمهٔ برگشت: تاریخچهٔ مرورگر با دکمهٔ برگشت خود بله تداخل دارد. مهارت در React از
MemoryRouterو در Vue ازcreateMemoryHistory()استفاده میکند. - اعتبارسنجی
initData: داده‌ای که بله دربارهٔ کاربر به مینیاپ میدهد باید سمت سرور با HMAC-SHA256 و توکن بازو بررسی شود، نه در مرورگر. مستندات بله این را با نمادگذاری تلگرام توضیح داده است. تاریخauth_dateرا هم بسنجید تا دادهٔ کهنه پذیرفته نشود.
پرداخت در بازوی بله با بله پی
پرداخت درون بازو دو مرحله دارد. اول بله pre_checkout_query را می‌فرستد و بازو با answerPreCheckoutQuery جواب میدهد. بعد پیام successful_payment می‌رسد و آن‌جا سفارش را ثبت می‌کنید. مستندات رسمی بله صریح است: اگر بازو ظرف حداکثر ۱۰ ثانیه به PreCheckoutQuery جواب ندهد، پرداخت لغو میشود. مهارت هم همین ترتیب را به دستیار یاد میدهد: اول جواب سریع، بعد کار سنگین.
طبق همان مستندات، پرداخت از کیف پول بله انجام میشود، provider_token بازو را از @botfather می‌گیرید، توکن آزمایشی هم وجود دارد و مبلغ LabeledPrice به ریال است. اگر درگاهی بیرون از بله مثل زرین‌پال می‌خواهید، مهارت درگاه پرداخت ایرانی برای همان کار است.
یک جلسه کار با این مهارت چه شکلی دارد؟
فرض کنید به Claude Code می‌گویید: «یک بازوی بله می‌خواهم که سؤال‌های فارسی را با مدل OpenAI جواب بدهد و با وب‌هوک کار کند.» مهارت انتخاب، دستیار را سراغ bale-ai-bot می‌فرستد. انتظار میرود دستیار قالب وب‌هوک FastAPI را مبنا بگیرد، توکن بازو و کلید OpenAI را از متغیر محیطی بخواند (مثلاً BALE_BOT_TOKEN و OPENAI_API_KEY) و تکه‌تکه کردن جواب‌های بلند را از اول در کد بگذارد. ثبت وب‌هوک با setWebhook و نشانی HTTPS سرورتان هم کاری است که خودتان باید انجام بدهید. نتیجهٔ هر پروژه فرق میکند و کد را باید روی یک بازوی آزمایشی امتحان کنید.
نصب مهارت بله در Claude Code، Codex و Cursor
این مهارت برای دستیارهای برنامهنویسی است. در یک گفتگوی معمولی کمتر به کار می‌آید و مخزن فایل zip برای بارگذاری در claude.ai هم ندارد. محل نصب طبق راهنمای سازنده:
| برنامه | محل نصب |
|---|---|
| Claude Code | ~/.claude/skills/ |
| OpenAI Codex | ~/.codex/skills/ |
| Google Antigravity | ~/.gemini/config/skills/ |
| Cursor | پوشهٔ .cursor/rules/ و فایل .cursorrules در پروژه (فایل قانون، نه مهارت) |
| GitHub Copilot | فایل copilot-instructions.md در پوشهٔ .github پروژه |
راه مطمئن‌تر این است که اول مخزن را کلون کنید، اسکریپت را بخوانید و بعد اجرایش کنید:
git clone https://github.com/tmolavi/bale-bot-skills
cd bale-bot-skills
bash install.sh --claudeاسکریپت هر پوشهٔ skills/ را در پوشهٔ برنامه‌هایی کپی میکند که روی کامپیوترتان پیدا کند. اگر نشانی پوشهٔ یک پروژه را به آن بدهید، قانون‌های Cursor را هم در آن پروژه می‌گذارد. راه دستی هم همان یک دستور است: داخل مخزن کلون‌شده cp -r skills/* ~/.claude/skills/.
دو نکته از خواندن خود اسکریپت‌ها:
- دستور یک‌خطی
curl … | bash: اسکریپت پوشهٔskillsرا کنار خودش جست‌وجو میکند. وقتی از اینترنت مستقیم به bash داده شود، آن پوشه را فقط اگر در پوشهٔ مخزن کلون‌شده باشید پیدا میکند. اگر بعد از اجرا پوشه‌ای در~/.claude/skills/ندیدید، از راه کلون بروید. - ویندوز: اسکریپت PowerShell مخزن فقط برای Antigravity و Codex نصب میکند، نه Claude Code. در ویندوز اسکریپت bash را در Git Bash یا WSL اجرا کنید.
فرق مهارت با سرور MCP را در تفاوت Skill و MCP نوشته‌ایم و برای انتخاب برنامه راهنمای انتخاب کلاینت MCP را ببینید.
قبل از اجرای کد بازو روی سرور
- بررسی گواهی TLS را روشن نگه دارید. چند جای مخزن این بررسی را خاموش میکند: کلاینت PHP در خود مهارت و قالب
BaleBotCore.php، قالب Node.js و قالب پایتون، و راهنمای رفع مشکل شبکه هم خاموش کردنش را پیشنهاد میدهد. توکن بازو داخل نشانی هر درخواست است، پس از دستیار صریح بخواهید این تنظیم را دست نزند. - کد اعتبارسنجی
initDataرا با مستندات بله مقایسه کنید. یک خطای کوچک در ترتیب کلید و داده، بررسی را بی‌اثر میکند. - به‌جای حذف
X-Frame-Options، فقطframe-ancestorsرا تنظیم کنید. بخش CSP مهارت حذف این سرآیند را پیشنهاد میدهد و مقدار جایگزینش،ALLOWALL، مقدار معتبری نیست. مقدارframe-ancestors 'self' https://web.bale.ai https://*.bale.aiبه‌تنهایی کافی است. - توکن و کلیدها را در متغیر محیطی بگذارید، نه در کد و نه در مخزن.
- این مهارت غیررسمی و تازه است. سازنده‌اش بله نیست، مخزن یک commit اولیه دارد و تنها بررسی خودکارش وجود فایل‌ها را می‌سنجد. مرجع درستی هر متد، مستندات رسمی بله است. مجوز مخزن MIT است.
بعد از ساخت بازو: دستیار خودتان هم در بله پیام بدهد
این مهارت کد بازو را می‌نویسد. کار دیگری هم هست که بازو برای خود شما انجام میدهد: با سرور MCP بله دستیارتان از طریق یک بازو وقتی کار طولانی‌اش تمام شد خبرتان میکند و جایی که تصمیم با شماست سؤال می‌پرسد. روشش را در اتصال هوش مصنوعی به ربات بله نوشته‌ایم. اگر هنوز دستیارتان را به بازارچه وصل نکرده‌اید، اتصال دستیار و راهنمای MCP نقطهٔ شروع است.
بازوی بعدی را با دستیار بسازید: مهارت ساخت بات و مینیاپ بله را دریافت کنید.
سؤال‌های پرتکرار
چطور در بله هوش مصنوعی داشته باشم؟
باید بازوی خودتان را بسازید: در بله از @botfather یک بازو و توکن بگیرید، کدی بنویسید که پیام را بگیرد و به یک مدل زبانی مثل ChatGPT یا Claude بفرستد و جواب را برگرداند، و آن کد را روی سرور خودتان اجرا کنید. مهارت «ساخت بات و مینیاپ بله» کمک میکند دستیار برنامهنویسی این کد را با قواعد خود بله بنویسد.
این مهارت خودش یک بازوی آماده است؟
نه. مجموعهای از دستورالعمل و قالب کد است که دستیار برنامهنویسی میخواند. ساختن بازو در @botfather، میزبانی کد روی سرور و کلید API مدل زبانی با خودتان است.
API بازوی بله با تلگرام چه فرقی دارد؟
طبق مستندات رسمی بله، API بازو بر پایهٔ API بات تلگرام و با تغییرات جزئی طراحی شده است. نشانی پایه tapi.bale.ai است، پرداخت از کیف پول بله میگذرد و مبلغها ریالی است. همین تفاوتهای کوچک است که دستیار بدون مهارت حدس میزند.
مهارت را در کدام برنامهها میشود نصب کرد؟
طبق راهنمای سازنده، در Claude Code، OpenAI Codex و Google Antigravity به شکل مهارت، و در Cursor و GitHub Copilot به شکل فایل قانون پروژه. این مهارت برای کدنویسی است، پس در دستیارهای برنامهنویسی بیشترین فایده را دارد.
پاسخ به pre_checkout_query در بله چقدر وقت دارد؟
طبق مستندات رسمی بله، بازو باید حداکثر ظرف ۱۰ ثانیه به این آپدیت جواب بدهد، وگرنه پرداخت لغو میشود. مهارت هم همین را به دستیار یاد میدهد: اول answerPreCheckoutQuery، بعد کار سنگین مثل ثبت سفارش.
کد نمونههای مهارت را میشود مستقیم روی سرور گذاشت؟
بهتر است نه. چند قالب مخزن بررسی گواهی TLS را خاموش میکنند، در حالی که توکن بازو داخل نشانی درخواست میرود. از دستیار بخواهید بررسی گواهی را روشن نگه دارد و کد اعتبارسنجی را با docs.bale.ai مقایسه کنید.
