کتابخانه پروتکل رسمی BaleX
کتابخانه BaleX یک پیادهسازی مستقل، سبک، مدرن و فوقالعاده سریع از پروتکل ارتباطی پیامرسان بله (Bale Messenger) سمت سرور بر پایه باینری (Protobuf / gRPC-Web / WebSocket) و بات رسمی بله (docs.bale.ai) است که در محیط Node.js / TypeScript پیادهسازی شده و از اتصال و اجرای مستقیم از طریق زبان Go (Golang) به طور کامل پشتیبانی میکند.
maviz-ws.bale.ai تبادل داده میکند که موجب مصرف ناچیز رم (کمتر از ۲۰ مگابایت)، سرعت میلیثانیهای و امنیت بالا میشود.
ویژگیهای برجسته BaleX
ارتباط باینری Protobuf خالص
انکود و دیکود کاملاً بومی و خالص پکتهای پروتکل بله بدون هیچ وابستگی سنگین خارجی.
عملیات بانکی شتابی
پشتیبانی کامل از کارتبهکارت، استعلام شتابی نام دارنده کارت و پاکت هدیه طلای بله.
موتور هوشمند ضد مسدودی
شبیهسازی تاخیر طبیعی تایپ، تاخیر متغیر خواندن پیامها، کنترل سین زدن و رفتار انسانی کامل.
۵۳ سرویس و ۶۳۶ متد
پوشش صد درصدی تمام قابلیتهای استخراجشده از پروتکل رسمی بله همراه با پراکسیهای خودکار.
روش ۱: نصب مستقیم از گیتهاب (GitHub)
شما میتوانید این کتابخانه را مستقیماً از مخزن گیتهاب بر روی پروژه خود نصب نمایید:
# نصب با نام کاربری و مخزن گیتهاب
npm install github:Zellias/balex
# یا نصب با آدرس کامل Git (HTTPS)
npm install git+https://github.com/Zellias/balex.git
# یا با Yarn و pnpm
pnpm add github:Zellias/balex
yarn add github:Zellias/balex
روش ۲: نصب از طریق رجیستری npm
npm install balex
شروع سریع (Quickstart)
نمونه کد کامل برای اتصال، گوش دادن به پیامها و پاسخگویی خودکار:
const { BaleClient, StringSession } = require('balex');
async function main() {
// ۱. ایجاد نمونه کلاینت با سشن ذخیره شده و رفتار انسانی
const client = new BaleClient({
session: new StringSession('سشن_ذخیره_شده_از_قبل'),
humanize: true, // فعالسازی تاخیر و تایپ طبیعی
logLevel: 'info'
});
// ۲. گوش دادن به پیامهای ورودی
client.on('message', async (msg) => {
console.log(`پیام جدید از ${msg.senderId}: ${msg.text}`);
if (msg.text === 'سلام') {
// پاسخ هوشمند با شبیهسازی خواندن، تاخیر تایپ و ارسال
await msg.reply('سلام و درود! پیام شما با موفقیت از طریق یوزربات BaleX دریافت شد 🌟');
}
});
// ۳. اتصال به شبکه وبسوکت بله
await client.connect();
console.log('یوزربات با موفقیت آنلاین شد!');
}
main().catch(console.error);
مدیریت اتصال و نشست (Connection & Session Lifecycle)
متدهای مدیریت چرخه حیات کلاینت و وضعیت اتصال به سرورهای بله:
اتصال به سرور وبسوکت (connect)
متد client.connect() اتصال بلادرنگ به سرور وبسوکت ماویز (wss://maviz-ws.bale.ai/ws/) را با استفاده از شناسه کاربر و JWT برقرار میکند و دریافت زنده رویدادها را آغاز مینماید:
// اتصال و ثبت هارتبیت حضور آنلاین
await client.connect();
console.log('وضعیت اتصال:', client.isConnected); // true
قطع اتصال سوکت (disconnect)
متد client.disconnect() ارتباط زنده را به شکل استاندارد خاتمه داده، تایمرهای هارتبیت را متوقف و منابع حافظه را آزاد میکند:
client.disconnect();
console.log('اتصال قطع شد. وضعیت:', client.isConnected); // false
احراز هویت و ورود به حساب (Authentication)
فرآیند لاگین در پیامرسان بله در دو الی سه مرحله به صورت درخواستهای gRPC-Web Unary روی سرور رسمی https://maviz-ws.bale.ai انجام میشود.
مرحله ۱: درخواست ارسال پیامک (sendCode)
متد client.sendCode(phoneNumber) کد تایید ورود را به شماره همراه کاربر ارسال میکند و شناسه تراکنش امنیتی transactionHash را بازمیگرداند:
// شماره همراه با صفر، بدون صفر یا پیشوند بینالمللی پذیرفته میشود
const res = await client.sendCode('09372570490');
console.log('کد پیامک شد. شناسه تراکنش:', res.transactionHash);
مرحله ۲: اعتبارسنجی کد ۵ رقمی (signIn)
متد client.signIn(code, transactionHash) کد ۵ رقمی دریافتی از پیامک را ارسال نموده و در صورت صحت، سشن را ایجاد و کلاینت را متصل میکند. ارقام فارسی (مانند ۱۵۰۱۱) به طور خودکار به ارقام انگلیسی تبدیل میگردند:
try {
const result = await client.signIn('15011');
console.log('ورود موفقیتآمیز بود!');
console.log('نام حساب:', result.user.name);
console.log('توکن JWT:', result.jwt);
} catch (error) {
if (error.message.includes('PHONE_PASSWORD_INVALID')) {
console.log('حساب دارای تایید دومرحلهای است؛ مرحله بعد را اجرا کنید.');
} else {
console.error('خطای ورود:', error.message);
}
}
مرحله ۳: تایید رمز دومرحلهای (signInWithPassword)
در صورتی که حساب کاربر دارای گذرواژه ابری دومرحلهای (۲FA) باشد، با متد client.signInWithPassword(password, transactionHash) احراز هویت را کامل کنید:
const session = await client.signInWithPassword('رمز_دومرحلهای_حساب');
console.log('لاگین دو مرحلهای تکمیل شد. خوش آمدید:', session.user.name);
ذخیره و بازیابی نشست (Session Persistence)
نیازی به ورود مجدد و دریافت پیامک در هر بار اجرای برنامه نیست؛ BaleX از دو کلاس StringSession و FileSession پشتیبانی میکند:
const { BaleClient, StringSession, FileSession } = require('balex');
// ذخیره سشن به صورت یک رشته متنی فشرده
const sessionString = client.session.save();
console.log('سشن شما:', sessionString);
// استفاده مجدد در اجراهای بعدی بدون نیاز به کد پیامکی:
const bot = new BaleClient({
session: new StringSession(sessionString)
});
await bot.connect();
console.log('ورود خودکار با موفقیت انجام شد!');
خروج از حساب کاربری (logout)
متد client.logout() درخواست لغو سشن رسمی (SignOut) را به سرورهای بله ارسال نموده، توکن محلی را پاکسازی و سوکت را میبندد:
await client.logout();
console.log('با موفقیت از حساب کاربری خارج شدید.');
پیامرسانی و گفتگوها (Messaging)
ارسال پیام متنی با پشتیبانی کامل از ریپلای، کوت (نقلقول) و شبیهسازی هوشمند تاخیر انسانی:
ارسال پیام پیشرفته (sendMessage)
// ۱. ارسال پیام ساده به کاربر یا گروه
await client.sendMessage(123456789, 'سلام! پیام ارسالشده از طریق BaleX 🚀');
// ۲. ارسال با ریپلای به پیام دیگر و تعیین مدت شبیهسازی تایپ
await client.sendMessage(123456789, 'پاسخ به سوال شما...', {
replyToMessageId: 987654321012n,
simulateTyping: true,
typingDuration: 2500 // ۲.۵ ثانیه نمایش در حال تایپ
});
ارسال پیام متنی سریع (sendTextMessage)
// ارسال پیام به چت خصوصی (کاربر)
await client.sendTextMessage(123456789, 'سلام کاربر گرامی');
// ارسال پیام به گروه با مشخص کردن آرگومان isGroup = true
await client.sendTextMessage(987654321, 'اطلاعیه جدید گروه', true);
تایید تحویل و خواندهشدن پیامها (Read Receipts)
ارسال سیگنال دریافت (یک تیک خاکستری) و خوانده شدن (دو تیک آبی):
const peer = { type: 1, id: 123456789 }; // کاربر مقصد
const messageDate = Date.now();
// ثبت وضعیت دریافت توسط کلاینت (Delivered)
await client.markAsReceived(peer, messageDate);
// ثبت وضعیت خواندهشدن (Seen / دو تیک آبی)
await client.markAsRead(peer, messageDate);
سامانه جامع رویدادها و کاتالوگ ۶۰+ رویداد زنده سوکت
کتابخانه BaleX از طریق استریم اختصاصی WebSocket (بر بستر bale.messaging.v2.Messaging) از تمامی بیش از ۶۰ رویداد رسمی پروتکل بله پشتیبانی میکند. در ادامه جدول دستهبندی شده کامل رویدادها، تگهای وایر، و کدهای نمونه هر بخش آورده شده است.
کاتالوگ جامع و دستهبندی شده بیش از ۶۰ رویداد رسمی بله
| نام رویداد (Event) | تگ وایر (Tag) | دستهبندی | شرح و کاربرد در بله |
|---|---|---|---|
message | 55 | پیامرسانی | دریافت پیام جدید (متنی، چندرسانهای، پاکت هدیه، سرویس) با متدهای هوشمند |
messageEdit | 162 | پیامرسانی | ویرایش متن، کپشن یا محتوای پیام ارسالشده |
messageDelete | 46 | پیامرسانی | حذف یک یا چند پیام در گفتگو توسط کاربر یا مدیر |
chatClear | 47 | پیامرسانی | پاکسازی کامل تاریخچه گفتگو برای دو طرف |
chatDelete | 48 | پیامرسانی | حذف کل گفتگو از لیست چتها |
messageReceived | 54 | پیامرسانی | تایید رسیدن پیام به دستگاه مقصد (تکتیک خاکستری) |
messageRead | 19 | پیامرسانی | تایید خوانده شدن پیام توسط مخاطب (دو تیک آبی) |
messageReadByMe | 50 | پیامرسانی | علامتگذاری پیام به عنوان خواندهشده توسط اکانت خودمان |
chatShow | 93 | پیامرسانی | خروج گفتگو از حالت مخفی و نمایش مجدد در لیست چتها |
chatArchive | 94 | پیامرسانی | آرشیو شدن گفتگو یا پوشه |
chatFavourite | 95 | پیامرسانی | افزودن گفتگو به برگزیدهها (Favorite) |
messageDateChanged | 163 | پیامرسانی | تغییر برچسب زمانی پیام |
stickerCollectionsChanged | 164 | پیامرسانی | بهروزرسانی کالکشنها و پکیجهای استیکر کاربر |
messageQuotedChanged | 169 | پیامرسانی | تغییر یا حذف پیام مرجع ریپلای شده |
mentionReadByMe | 52829 | پیامرسانی | سین شدن پیامهای حاوی منشن کاربر |
pinnedDialogsChanged | 52830 | پیامرسانی | تغییر در لیست یا ترتیب گفتگوهای پینشده |
dialogsMarkedAsRead | 54335 | پیامرسانی | علامتگذاری گروهی گفتگوها به عنوان خواندهشده |
dialogsMarkedAsUnread | 54336 | پیامرسانی | علامتگذاری گروهی چتها به عنوان خواندهنشده |
dialogsUnpinned | 54339 | پیامرسانی | برداشته شدن سنجاق و پین گفتگو |
messagePinned | 54340 | پیامرسانی | پین و سنجاق شدن پیام جدید در گروه یا کانال |
messagesUnPinned | 54341 | پیامرسانی | برداشته شدن سنجاق یک یا چند پیام |
dialogArchiveStatus | 54345 | پیامرسانی | تغییر وضعیت فعال/غیرفعال آرشیو گفتگو |
messageStreamChunks | 54351 | پیامرسانی | دریافت بستههای زنده متن تولیدی هوش مصنوعی یا استریم (Streaming) |
reaction | 222 / 52825 | واکنشها | ثبت، تغییر یا حذف واکنش ایموجی روی پیام توسط کاربران |
messageNewReaction | 54323 | واکنشها | ثبت واکنش جدید با جزئیات کامل کاربر و ایموجی |
messageReactionsReadByMe | 52832 | واکنشها | سین شدن واکنشهای ثبتشده توسط کاربر |
typing | 6 | حضور و وضعیت | شروع تایپ، ضبط صدا، ارسال ویدیو یا آپلود فایل توسط مخاطب |
typingStop | 81 | حضور و وضعیت | توقف وضعیت در حال نوشتن مخاطب |
userOnline | 7 | حضور و وضعیت | آنلاین شدن کاربر در پلتفرم بله |
userOffline | 8 | حضور و وضعیت | آفلاین شدن کاربر همراه با برچسب زمانی آخرین بازدید |
userLastSeen | 9 | حضور و وضعیت | تغییر در تنظیمات حریم خصوصی یا وضعیت آخرین بازدید کاربر |
presence | Alias | حضور و وضعیت | شنونده سراسری هرگونه تغییر وضعیت آنلاین/آفلاین/بازدید |
userAvatarChanged | 16 | کاربر و نمایه | تغییر یا حذف عکس پروفایل کاربر |
userNameChanged | 32 | کاربر و نمایه | تغییر نام و نامخانوادگی نمایشی کاربر |
userLocalNameChanged | 51 | کاربر و نمایه | تغییر نام ذخیره شده مخاطب در دفترچه تلفن |
userContactsChanged | 134 | کاربر و نمایه | بهروزرسانی لیست مخاطبین همگامشده |
userNickChanged | 209 | کاربر و نمایه | تغییر یا ثبت نامکاربری عمومی (Username) |
userAboutChanged | 210 | کاربر و نمایه | تغییر بیوگرافی (About / Bio) نمایه کاربر |
userPreferredLanguagesChanged | 212 | کاربر و نمایه | تغییر زبان مورد نظر کاربر در تنظیمات بله |
userTimeZoneChanged | 216 | کاربر و نمایه | تغییر منطقه زمانی حساب کاربری |
userBotCommandsChanged | 217 | کاربر و نمایه | تغییر در لیست دستورات ثبتشده برای ربات |
userBlocked | 2629 | کاربر و نمایه | مسدودسازی یک کاربر (بلاک) |
userUnblocked | 2630 | کاربر و نمایه | رفع مسدودیت کاربر (آنبلاک) |
phoneNumberChanged | 52803 | کاربر و نمایه | تغییر شماره تلفن همراه متصل به حساب کاربری |
contactsAdded | 40 | کاربر و نمایه | افزوده شدن مخاطب جدید به دفترچه تلفن |
contactsRemoved | 41 | کاربر و نمایه | حذف مخاطب از دفترچه تلفن بله |
allContactsRemoved | 54353 | کاربر و نمایه | پاکسازی کامل تمام مخاطبین حساب |
groupOnline | 33 | گروه و کانال | تغییر تعداد اعضای آنلاین گروه |
groupNicknameChanged | 57 | گروه و کانال | تغییر آیدی یا لینک عمومی گروه |
groupMessagePinned | 721 | گروه و کانال | پین شدن پیام جدید در گروه |
groupPinRemoved | 722 | گروه و کانال | برداشته شدن سنجاق پیام گروه |
groupRestrictionChanged | 723 | گروه و کانال | تغییر در محدودیتهای اعمالشده روی گروه |
groupTitleChanged | 2609 | گروه و کانال | تغییر عنوان و نام گروه |
groupAvatarChanged | 2610 | گروه و کانال | تغییر عکس نمایه و آواتار گروه |
groupMemberChanged | 2612 | گروه و کانال | تغییر وضعیت یا نقش عضو در گروه |
groupExtChanged | 2613 | گروه و کانال | تغییر اکستنشنها و ویژگیهای تکمیلی گروه |
groupMembersUpdated | 2614 | گروه و کانال | بهروزرسانی جامع لیست اعضای گروه |
groupTopicChanged | 2616 | گروه و کانال | تغییر موضوع یا دستهبندی موضوعی گروه |
groupAboutChanged | 2617 | گروه و کانال | تغییر توضیحات و بیوگرافی گروه |
groupOwnerChanged | 2619 | گروه و کانال | انتقال مالکیت اصلی گروه به کاربر دیگر |
groupHistoryShared | 2620 | گروه و کانال | تغییر وضعیت دسترسی اعضای جدید به تاریخچه چت |
groupMembersCountChanged | 2622 | گروه و کانال | تغییر تعداد کل اعضای گروه |
groupMemberDiff | 2623 | گروه و کانال | رویداد پیوستن یا خروج عضو به گروه |
groupCanSendMessagesChanged | 2624 | گروه و کانال | تغییر مجوز ارسال پیام اعضا (بستن یا باز کردن چت) |
groupCanViewMembersChanged | 2625 | گروه و کانال | تغییر مجوز دیدن لیست اعضا توسط کاربران عادی |
groupCanInviteMembersChanged | 2626 | گروه و کانال | تغییر دسترسی اعضا جهت دعوت دیگران |
groupMemberAdminChanged | 2627 | گروه و کانال | ارتقا به مدیر یا تنزل مقام در گروه |
groupBecameOrphaned | 2628 | گروه و کانال | بدون مالک و مدیر شدن گروه |
groupMemberPermissionsChanged | 52804 | گروه و کانال | تغییر ریزمجوزهای یک عضو خاص در گروه |
groupDefaultPermissionsChanged | 52805 | گروه و کانال | تغییر مجوزهای پیشفرض عمومی گروه |
channelNickChanged | 2880 | گروه و کانال | تغییر نامکاربری یا شناسه عمومی کانال |
channelAdvertisementTypeChanged | 52801 | گروه و کانال | تغییر نوع تبلیغات فعال درون کانال |
channelAdTagIdChanged | 52802 | گروه و کانال | تغییر شناسه تگهای تبلیغاتی کانال |
channelSignMessagesChanged | 54354 | گروه و کانال | فعال یا غیرفعال شدن امضای نام نویسنده در کانال |
slowModeChanged | 54355 | گروه و کانال | تنظیم حالت آرام (Slow Mode) و تاخیر ارسال پیام اعضا |
callStarted | 52807 | تماسها | شروع تماس صوتی یا تصویری |
callAccepted | 52808 | تماسها | پذیرش و برقراری تماس توسط مخاطب |
callDiscarded | 52809 | تماسها | قطع شدن، رد یا پایان یافتن تماس |
callReceived | 52810 | تماسها | دریافت زنگ تماس ورودی |
groupCallStarted | 52811 | تماسها | شروع تماس گروهی درون گروه یا کانال |
groupCallEnded | 52812 | تماسها | پایان تماس صوتی یا تصویری گروهی |
callReactionSent | 52813 | تماسها | ارسال واکنش ایموجی حین مکالمه زنده |
callUpgraded | 52816 | تماسها | ارتقای تماس دو نفره به تماس گروهی |
peersInvited | 52817 | تماسها | دعوت کاربران جدید به تماس در حال اجرا |
multiPeerCallStarted | 52818 | تماسها | آغاز کنفرانس و تماس چندطرفه |
peersStateChanged | 52819 | تماسها | تغییر وضعیت اعضا در تماس (میکروفون، دوربین، ...) |
call | Alias | تماسها | شنونده جامع و یکپارچه تمامی رویدادهای تماس |
giftPacket | Custom | پاکت هدیه | دریافت پیام پاکت هدیه نقدی ریالی در گفتگو |
goldGiftPacket | Custom | پاکت هدیه | دریافت پیام پاکت هدیه طلای بله در گفتگو |
giftPacketOpened | Service 17/18 | پاکت هدیه | رویداد باز شدن پاکت هدیه توسط یکی از کاربران و دریافت مبلغ |
miniAppData | Service 21 | مینیاپ | دریافت دادههای ارسالشده از مینیاپ/وباپ به ربات |
serviceMessage | Tag 11 | پیام سرویس | پیامهای سیستمی بله (عضویت، اخراج، تغییر عنوان، ...) |
groupCreated | Service 1 | پیام سرویس | رویداد ساخته شدن گروه جدید |
userInvited | Service 2 | پیام سرویس | رویداد افزوده شدن کاربر جدید به گروه |
userKicked | Service 3 | پیام سرویس | رویداد اخراج کاربر از گروه |
userLeft | Service 4 | پیام سرویس | رویداد ترک گروه توسط عضو |
connected | Lifecycle | سوکت | اتصال موفق به سرور WebSocket و شروع نشست کاربری |
disconnected | Lifecycle | سوکت | قطع ارتباط سوکت همراه با کد و دلیل قطع |
status | Lifecycle | سوکت | تغییر وضعیت کانکشن (CONNECTING, CONNECTED, ...) |
error | Error | خطاها | بروز هرگونه خطای شبکه، اعتبارسنجی یا سرور |
update | Universal | سوکت | دریافت فریم خام تمام بهروزرسانیهای ورودی سوکت |
ویژگیها و هلپرهای عملیاتی پیشرفته رویداد message
شیء دریافتی در رویداد message مجهز به دهها پرچم نوع محتوا و توابع عملیاتی جهت پاسخگویی سریع، واکنش، باز کردن پاکت هدیه و مدیریت پیام است:
client.on('message', async (msg) => {
console.log('فرستنده:', msg.senderId);
console.log('مخاطب/گفتگو:', msg.peer);
console.log('متن پیام یا کپشن:', msg.text);
console.log('شناسه تصادفی (Random ID):', msg.randomId);
console.log('زمان ارسال:', msg.date);
// پرچمهای محتوا
if (msg.isPhoto) console.log('پیام حاوی تصویر است 📸');
if (msg.isVoice) console.log('پیام حاوی ویس است 🎙️');
if (msg.isAudio) console.log('پیام حاوی موزیک است 🎵');
if (msg.isVideo) console.log('پیام حاوی ویدیو است 🎥');
if (msg.isDocument) console.log('پیام حاوی سند یا فایل است 📄');
if (msg.isSticker) console.log('پیام حاوی استیکر است ✨');
// ۱. بررسی و باز کردن خودکار پاکت هدیه نقدی ریالی
if (msg.isGiftPacket) {
console.log('پاکت هدیه نقدی رسید! مبلغ کل:', msg.giftPacket.totalAmount, 'ریال');
const claimRes = await msg.claimGiftPacket(); // یا msg.openGiftPacket()
console.log('مبلغ برنده شده شما:', claimRes.amount, 'ریال');
console.log('لیست برندگان:', await msg.getGiftPacketReceivers());
}
// ۲. بررسی و باز کردن خودکار پاکت هدیه طلا
if (msg.isGoldGiftPacket) {
console.log('پاکت طلای بله رسید! شناسه:', msg.goldGiftPacket.packetId);
const goldWin = await msg.claimGoldGiftPacket(); // یا msg.openGoldGiftPacket()
console.log('میلیگرم طلای برنده شده:', goldWin.amount);
console.log('شناسههای برندگان طلا:', await msg.getGoldWinners());
}
// ۳. پاسخ هوشمند با شبیهسازی رفتار انسانی (Seen -> Thinking -> Typing -> Send)
if (msg.text === 'سلام') {
await msg.reply('درود! چطور میتونم کمکتون کنم؟ 👋');
}
// ۴. ارسال تایید تحویل و خواندهشدن
await msg.markAsReceived(); // تیک خاکستری
await msg.markAsRead(); // دو تیک آبی
// ۵. ثبت واکنش ایموجی
await msg.react('❤️');
// ۶. پین، فوروارد و حذف پیام
// await msg.forwardTo(targetPeer);
// await msg.pin();
// await msg.delete();
});
کد نمونه شنوندههای دستههای مختلف رویدادهای زنده سوکت
// ۱. رویدادهای ویرایش، حذف و پیام پینشده
client.on('messageEdit', (edit) => console.log(`پیام ${edit.rid} ویرایش شد:`, edit.message));
client.on('messageDelete', (del) => console.log(`پیامهای ${del.rids} حذف شدند.`));
client.on('messagePinned', (pin) => console.log(`پیام جدید در چت پین شد:`, pin));
// ۲. تیک دریافت و خوانده شدن
client.on('messageReceived', (recv) => console.log(`تحویل تا ${recv.startDate} (تکتیک)`));
client.on('messageRead', (read) => console.log(`خوانده شدن تا ${read.startDate} (دو تیک آبی)`));
// ۳. واکنشها (Reactions)
client.on('reaction', (react) => console.log(`تغییر واکنش پیام ${react.rid}:`, react.reactions));
client.on('messageNewReaction', (r) => console.log(`ریاکشن جدید از کاربر ${r.userId}: ${r.code}`));
// ۴. تایپینگ و حضور کاربر
client.on('typing', (t) => console.log(`کاربر ${t.userId} در حال نوشتن...`));
client.on('typingStop', (t) => console.log(`کاربر ${t.userId} از تایپ دست کشید.`));
client.on('userOnline', (u) => console.log(`🟢 کاربر ${u.userId} آنلاین شد.`));
client.on('userOffline', (u) => console.log(`🔴 کاربر ${u.userId} آفلاین شد. آخرین بازدید: ${new Date(Number(u.lastSeen))}`));
// ۵. گروهها و کانالها
client.on('groupTitleChanged', (g) => console.log(`عنوان گروه به ${g.title} تغییر کرد.`));
client.on('groupMemberDiff', (m) => console.log(`تغییرات اعضای گروه:`, m));
client.on('groupMemberAdminChanged', (a) => console.log(`تغییر مقام ادمین:`, a));
client.on('slowModeChanged', (s) => console.log(`تنظیم تاخیر ارسال گروه (SlowMode): ${s.seconds} ثانیه`));
// ۶. تماسهای صوتی و تصویری
client.on('callStarted', (c) => console.log(`تماس جدید آغاز شد:`, c));
client.on('callAccepted', (c) => console.log(`تماس برقرار شد:`, c));
client.on('callDiscarded', (c) => console.log(`تماس پایان یافت:`, c));
// ۷. پاکتهای هدیه و مینیاپها
client.on('giftPacketOpened', (open) => console.log(`پاکت هدیه توسط کاربر ${open.receiverUserId} باز شد. مبلغ: ${open.amount} ریال`));
client.on('miniAppData', (app) => console.log(`داده دریافتی از مینیاپ:`, app.data));
// ۸. چرخه حیات اتصال سوکت
client.on('connected', (info) => console.log(`✅ اتصال زنده برقرار شد (UID: ${info.uid})`));
client.on('disconnected', (evt) => console.warn(`⚠️ اتصال قطع شد (کد ${evt.code}): ${evt.reason}`));
client.on('error', (err) => console.error('خطای سوکت:', err));
await client.connect();
دریافت لیست گفتگوها (loadDialogs)
متد client.loadDialogs(limit, endDate) آخرین گفتگوها، گروهها و کانالهای کاربر را همراه با آخرین پیام بارگذاری مینماید:
const result = await client.loadDialogs(20);
result.dialogs?.forEach(d => {
console.log(`چت: ${d.title || d.peer?.id} | آخرین پیام: ${d.lastMessage?.textMessage?.text}`);
});
تاریخچه پیامهای چت (loadHistory)
متد client.loadHistory(peer, limit, date) برای دریافت پیامهای قبلی چت خصوصی یا گروه به همراه پیمایش تاریخچه (Pagination):
// دریافت ۵۰ پیام آخر
const history = await client.loadHistory(123456789, 50);
history.messages?.forEach(m => {
console.log(`[${m.date}] ${m.senderId}: ${m.message?.textMessage?.text}`);
});
ارسال چندرسانهای (Media Messaging)
پشتیبانی کامل از ساختار پروتوباف بله (Document تگ ۴ با فرمتهای DocumentEx):
ارسال عکس با پیشنمایش و کپشن (sendPhoto)
await client.sendPhoto(peerId, {
fileId: 1048576,
accessHash: 9876543210123456n,
fileSize: 245000,
name: 'image.jpg',
width: 1280,
height: 720,
caption: 'تصویر ارسالی از BaleX 📸'
});
ارسال پیام صوتی و ویس (sendVoice)
await client.sendVoice(peerId, {
fileId: 2097152,
accessHash: 8765432109876543n,
fileSize: 64000,
duration: 12, // ۱۲ ثانیه
waveForm: Buffer.from([0x01, 0x05, 0x1a, 0x22, 0x08]),
caption: 'پیام صوتی راهنما 🎙️'
});
ارسال موزیک و آهنگ (sendAudio)
await client.sendAudio(peerId, {
fileId: 3145728,
accessHash: 7654321098765432n,
fileSize: 5240000,
duration: 215, // ثانیه
name: 'track.mp3',
title: 'قطعه موسیقی زیبا',
performer: 'نام هنرمند',
caption: 'موزیک ارسالی 🎵'
});
ارسال ویدیو (sendVideo)
await client.sendVideo(peerId, {
fileId: 4194304,
accessHash: 6543210987654321n,
fileSize: 15400000,
width: 1920,
height: 1080,
duration: 45,
name: 'video.mp4',
caption: 'ویدیوی معرفی محصول 🎬'
});
ارسال فایل و اسناد (sendDocument)
await client.sendDocument(peerId, {
fileId: 5242880,
accessHash: 5432109876543210n,
fileSize: 1200000,
name: 'report.pdf',
mimeType: 'application/pdf',
caption: 'گزارش نهایی پروژه 📄'
});
ارسال استیکر بله (sendSticker)
await client.sendSticker(peerId, 102456, 1234567890n, 100);
console.log('استیکر ارسال شد!');
مدیریت پیامها و گفتگوها
ویرایش پیام (editMessage)
await client.editMessage(peerId, 104523n, 'متن اصلاحشده جدید ✏️');
console.log('پیام ویرایش شد.');
فوروارد پیامها (forwardMessages)
const toPeer = 123456789;
const fromPeer = 987654321;
const messageIds = [1001n, 1002n];
await client.forwardMessages(toPeer, fromPeer, messageIds);
console.log('پیامها فوروارد شدند.');
پین کردن پیام (pinMessage)
await client.pinMessage(peerId, 104523n);
console.log('پیام در بالای چت سنجاق شد 📌');
حذف پیامها (deleteMessages)
await client.deleteMessages(peerId, [1001n, 1002n]);
console.log('پیامهای مشخصشده حذف شدند 🗑️');
پاکسازی کل تاریخچه چت (clearChat)
await client.clearChat(peerId);
console.log('کل تاریخچه مکالمه پاکسازی گردید.');
مدیریت گروهها و کانالها
ساخت گروه جدید (createGroup)
const newGroup = await client.createGroup('تیم برنامهنویسی BaleX', [
123456789,
987654321
]);
console.log('گروه ساخته شد با شناسه:', newGroup.group?.id);
افزودن عضو به گروه (inviteMembers)
await client.inviteMembers(groupId, [1122334455]);
console.log('عضو جدید به گروه افزوده شد.');
اخراج عضو از گروه (kickMember)
await client.kickMember(groupId, 1122334455);
console.log('کاربر از گروه اخراج شد.');
تغییر نام گروه (setGroupTitle)
await client.setGroupTitle(groupId, 'نام جدید و رسمی گروه');
console.log('عنوان گروه بهروز شد.');
ترک گروه (leaveGroup)
await client.leaveGroup(groupId);
console.log('با موفقیت از گروه خارج شدید.');
کاربران، مخاطبین و پروفایل
مشخصات پروفایل کاربر (getUser)
const user = await client.getUser(123456789);
console.log('نام:', user.name);
console.log('نام کاربری:', user.username);
console.log('درباره من:', user.about);
اطلاعات گروه (getGroup)
const group = await client.getGroup(groupId);
console.log('عنوان گروه:', group.title);
console.log('تعداد اعضا:', group.membersCount);
لیست مخاطبین بله (getContacts)
const contacts = await client.getContacts();
contacts.users?.forEach(c => {
console.log(`مخاطب: ${c.name} | شماره: ${c.phone} | شناسه: ${c.id}`);
});
افزودن مخاطب به حساب (addContact / addContactByUid)
افزودن از طریق شماره تلفن یا شناسه مستقیم کاربری (UID):
// روش ۱: افزودن با شماره موبایل و نام دلخواه
await client.addContact('09120000000', 'علی محمدی');
// روش ۲: افزودن مستقیم با شناسه کاربری (UID)
await client.addContactByUid(123456789);
console.log('مخاطب با موفقیت به حساب کاربری اضافه شد.');
همگامسازی و واردسازی گروهی (importContacts)
وارد کردن لیست کامل مخاطبین به طور یکجا (Bulk Sync):
const res = await client.importContacts([
{ phone: '09121111111', name: 'مهندس رضایی' },
{ phone: '09122222222', name: 'خانم عباسی' },
{ phone: '09123333333', name: 'پشتیبانی فنی' }
]);
console.log('مخاطبین بلهای همگامشده:', res.users?.length);
حذف مخاطب (removeContact)
await client.removeContact(123456789);
console.log('مخاطب از لیست دفترچه تلفن حذف شد.');
جستجوی مخاطبین (searchContacts)
const results = await client.searchContacts('رضا');
results.users?.forEach(u => console.log(`یافت شد: ${u.name} (${u.id})`));
ویرایش مشخصات حساب (editName / editAbout)
// ویرایش نام نمایشی
await client.editName('توسعهدهنده BaleX');
// ویرایش متن درباره من (بیوگرافی)
await client.editAbout('یوزربات هوشمند و اتوماسیون پیشرفته بر بستر بله');
console.log('اطلاعات پروفایل بهروزرسانی شد.');
مدیریت نامکاربری (editUsername / checkUsername)
// بررسی در دسترس بودن آیدی
const check = await client.checkUsername('my_bot_channel');
console.log('آیا آیدی آزاد است؟', check.isAvailable);
// تنظیم یا تغییر آیدی حساب
if (check.isAvailable) {
await client.editUsername('my_bot_channel');
console.log('نام کاربری با موفقیت ثبت شد!');
}
مدیریت کاربران مسدود (blockUser / unblockUser / loadBlockedUsers)
// مسدود کردن کاربر اسپمر
await client.blockUser(123456789);
// رفع مسدودی کاربر
await client.unblockUser(123456789);
// دریافت لیست کامل افراد بلاکشده
const blocked = await client.loadBlockedUsers();
console.log('لیست سیاه:', blocked.users);
واکنشها و پوشهها
ثبت واکنش ایموجی (setReaction)
// ثبت ایموجی لایک، قلب، آتش و... روی پیام
await client.setReaction(peerId, 104523n, '❤️');
console.log('ریاکشن ثبت شد!');
حذف واکنش از پیام (removeReaction)
await client.removeReaction(peerId, 104523n, '❤️');
console.log('ریاکشن حذف گردید.');
مشاهده آمار واکنشهای پیام (getReactions)
const data = await client.getReactions(peerId, [104523n]);
console.log('آمار واکنشها:', data.results);
مدیریت پوشههای چت (createFolder / loadFolders / deleteFolder)
// ۱. دریافت لیست پوشهها
const folders = await client.loadFolders();
console.log('پوشههای من:', folders);
// ۲. ساخت پوشه جدید با دستهبندی چتها
const newFolder = await client.createFolder('کانالهای خبری', [
123456,
789101
]);
// ۳. حذف یک پوشه
await client.deleteFolder(newFolder.folderId);
نظرسنجی، کیفپول و رباتها
ارسال نظرسنجی و کوییز (sendPoll)
await client.sendPoll(peerId, 'بهترین زبان برنامهنویسی برای بکاند چیست؟', [
'JavaScript / Node.js',
'Go (Golang)',
'Python',
'Rust'
], {
isAnonymous: true, // نظرسنجی ناشناس
isMultipleChoice: false, // چند گزینهای
isQuiz: false // حالت کوییز و مسابقه
});
مدیریت نظرسنجی (createPoll / getPollResults / closePoll)
// دریافت نتایج آرای نظرسنجی
const results = await client.getPollResults(pollId);
console.log('نتایج آرا:', results);
// بستن و پایان پذیرش آرا در نظرسنجی
await client.closePoll(pollId);
console.log('نظرسنجی با موفقیت بسته شد.');
استعلام کیف پول و امتیازات بله (getWalletCredit / getWalletPoints)
// موجودی کیفپول ریالی
const credit = await client.getWalletCredit();
console.log('موجودی کیفپول:', credit);
// موجودی امتیازات بله
const points = await client.getWalletPoints();
console.log('امتیازات کسبشده:', points.balance);
کلیک روی دکمه شیشهای ربات (sendInlineCallback)
// شبیهسازی کلیک کاربر روی اینلاین کیبورد ربات
await client.sendInlineCallback(botPeerId, messageId, 'action_confirm_pay');
console.log('کلیک دکمه اینلاین شبیهسازی شد.');
پاکت هدیه معمولی نقدی (Cash Gift Packet)
قابلیت ارسال پاکت هدیه ریالی با کسر از موجودی کیفپول (بر بستر bale.giftpacket.v1.GiftPacket):
ارسال پاکت هدیه نقدی (sendGiftPacket)
ارسال پاکت هدیه به چت یا گروه با امکان تقسیم مساوی یا شانسی میان افراد:
// ارسال پاکت هدیه ۵۰۰ هزار ریالی بین ۵ نفر به صورت شانسی
const res = await client.sendGiftPacket({
peer: 123456789, // کاربر، گروه یا کانال مقصد
amount: 500000, // مبلغ کل پاکت (ریال)
count: 5, // تعداد افراد دریافتکننده
message: 'عیدی نوروز مبارک! 🌸', // متن روی پاکت
givingType: 0, // ۰: شانسی (Random)، ۱: مساوی (Equal)
coverId: 1, // طرح جلد پاکت
showTotalAmount: true // نمایش مبلغ کل برای همه
});
console.log('پاکت هدیه معمولی با موفقیت ارسال شد.');
باز کردن، دریافت و استعلام پاکت هدیه نقدی (openGiftPacket / claimGiftPacket / getGiftPacket)
متدهای کامل جهت باز کردن، دریافت وجه و دریافت لیست کامل برندگان و جزئیات پاکت هدیه:
// ۱. باز کردن و دریافت سهم نقدی (Claim)
const result = await client.claimGiftPacket({
peer: 123456789,
randomId: 9876543210123n, // شناسه تصادفی پیام پاکت
date: Date.now(),
walletId: 'WAL-12345' // شناسه کیفپول مقصد جهت واریز
});
console.log('وضعیت پاکت:', result.status); // 1: ACTIVE, 2: EXPIRED, 3: FINISHED
console.log('مبلغ برنده شده شما:', result.amount, 'ریال');
console.log('آیا برنده شدید؟', result.isCurrentWinner);
console.log('رتبه در باز کردن:', result.rank);
console.log('تعداد بازکنندگان:', result.openedCount);
// ۲. استعلام مشخصات کامل پاکت هدیه (getGiftPacket)
const details = await client.getGiftPacket({
peer: 123456789,
randomId: 9876543210123n
});
console.log('متن پاکت:', details.description);
console.log('تعداد کل جوایز:', details.winnerCount);
// ۳. استعلام لیست کامل دریافتکنندگان پاکت (getGiftPacketReceivers)
const receivers = await client.getGiftPacketReceivers({
peer: 123456789,
randomId: 9876543210123n
});
console.log('لیست برندگان:', receivers);
// ۴. دریافت توکن درگاه پرداخت پاکت هدیه
const payToken = await client.getGiftPacketPaymentToken({ token: 'tok_123', amount: 500000 });
// ۵. شنود رویداد باز شدن پاکت هدیه توسط کاربران چت
client.on('giftPacketOpened', (evt) => {
console.log(`کاربر ${evt.receiverUserId} پاکت هدیه را باز کرد و ${evt.amount} ریال برنده شد!`);
});
پاکت هدیه طلا (Gold Gift Packet)
ارسال شمش طلا بر حسب میلیگرم در قالب پاکت هدیه بلهبانک (بر بستر bale.balebank.v1.GoldGiftPacket):
ارسال پاکت هدیه طلا (sendGoldGiftPacket)
const goldPacket = await client.sendGoldGiftPacket({
peer: 123456789,
amountMilligrams: 100, // ۱۰۰ میلیگرم طلا
count: 3, // ۳ برنده
message: 'هدیه طلای بله تقدیم به شما! 🪙',
givingType: 0 // ۰: شانسی، ۱: مساوی
});
console.log('شناسه پاکت طلای ارسالی:', goldPacket.giftPacketId);
باز کردن پاکت طلا و دریافت لیست برندگان (openGoldGiftPacket / claimGoldGiftPacket / getGoldWinners)
const packetId = 987654321n;
// ۱. باز کردن و دریافت سهم شمش طلا (Claim)
const claimResult = await client.claimGoldGiftPacket(packetId);
console.log('میلیگرم طلای برنده شده:', claimResult.amount);
console.log('تعداد افراد بازکننده:', claimResult.openedCount);
console.log('رتبه شما:', claimResult.rank);
// ۲. مشاهده شناسههای کاربری برندگان پاکت طلا
const winners = await client.getGoldWinners(packetId);
console.log('شناسههای برندگان طلا:', winners.winnerIds);
// ۳. باز کردن مستقیم از طریق رویداد پیام (MessageEvent Helper)
client.on('goldGiftPacket', async (msg) => {
console.log('پیام پاکت طلا رسید! شناسه:', msg.goldGiftPacket.packetId);
const win = await msg.claimGoldGiftPacket();
console.log('طلای برنده شده:', win.amount, 'میلیگرم');
});
مینیاپها و وباپهای بله (Mini Apps & Parameter Engine)
کتابخانه BaleX مجهز به موتور اختصاصی MiniAppUtils کاملاً سازگار با استاندارد تلگرام و بله برای تولید و اعتبارسنجی پارامترهای مینیاپها است. با این ماژول میتوانید رشته initData بسازید، آن را با توکن ربات امضا و اعتبارسنجی رمزی کنید، و آدرس نهایی لانچ وباپ را همراه با پارامترهای تم تولید نمایید.
ساخت پارامترهای مینیاپ به صورت آفلاین یا با توکن ربات (MiniAppUtils)
const { MiniAppUtils, ScreenMode, MiniAppEvent } = require('balex');
const botToken = '123456789:ABCdefGhIJKlmNoPQRstuVWXyz';
// ۱. تولید رشته استاندارد initData با امضای معتبر HMAC-SHA256
const initData = MiniAppUtils.createInitData({
user: {
id: 987654321,
first_name: 'رضا',
username: 'rezabalex',
language_code: 'fa'
},
queryId: 'AAH_test123',
authDate: Math.floor(Date.now() / 1000),
startParam: 'ref_bonus_100',
botToken // اختیاری جهت ایجاد هش امضای معتبر
});
console.log('رشته اعتبارسنجی مینیاپ:', initData);
// ۲. اعتبارسنجی امضای امنیتی در سمت بکاند ربات (Validation)
const validation = MiniAppUtils.validateInitData(initData, botToken);
if (validation.valid) {
console.log('امضای مینیاپ کاملاً معتبر است! کاربر تایید شد:', validation.data.user);
} else {
console.error('دادههای مینیاپ نامعتبر یا دستکاری شده است:', validation.error);
}
// ۳. پارس کردن رشته initData به آبجکت تایپشده
const parsed = MiniAppUtils.parseInitData(initData);
console.log('شناسه کوئری:', parsed.query_id);
console.log('پارامتر استارت دیپلینک:', parsed.start_param);
// ۴. ساخت آدرس کامل باز کردن مینیاپ درون وبویو (Launch URL)
const launchUrl = MiniAppUtils.buildMiniAppUrl({
webAppUrl: 'https://my-app.bale.ai',
initData,
themeParams: {
bg_color: '#0e1015',
text_color: '#f3f4f6',
button_color: '#10b981'
}
});
console.log('آدرس نهایی جهت بارگذاری در WebView:', launchUrl);
دریافت پارامترهای راهاندازی از سرور بله (createMiniAppParams)
این متد هش رسمی سرور بله را دریافت کرده و تمام پارامترهای احراز هویت وباپ را آماده میسازد:
پشتیبانی کامل از استاندارد تلگرام و بله برای مینیاپلیکیشنها (Appzar / Ketf) شامل تولید initData، هش امنیتی و پارامترهای تم.
ساخت کامل پارامترهای راهاندازی مینیاپ (createMiniAppParams)
این متد هش امنیتی رسمی سرور بله را دریافت کرده و تمام پارامترهای احراز هویت وباپ را برای باز کردن درون WebView آماده میسازد:
const botId = 123456; // شناسه ربات دارنده مینیاپ
// ساخت پارامترهای کامل launch params و initData
const appParams = await client.createMiniAppParams(botId, {
appUrl: 'https://my-mini-app.example.com',
startParam: 'ref_user_789',
platform: 'weba'
});
console.log('رشته اعتبارسنجی (initData):', appParams.initData);
console.log('امضای امنیتی سرور (hash):', appParams.hash);
console.log('آدرس کامل جهت بارگذاری در وبویو:', appParams.launchUrl);
// https://my-mini-app.example.com/#tgWebAppData=query_id%3D...%26user%3D...%26hash%3D...
دریافت آدرس مینیاپ از سرور (getMiniAppUrl)
متد رسمی bale.appzar.v1.Appzar.GetMiniAppUrl برای دریافت آدرس وباپ با امضای سرور:
const { url, queryId } = await client.getMiniAppUrl({
botUserId: botId,
screenMode: 1, // ۱: تمامصفحه (Fullscreen)، ۰: پیشفرض
directLink: 'start_param_value'
});
console.log('لینک اجرای وباپ:', url);
دریافت هش امنیتی وباپ (getWebappHash)
متد bale.ketf.v1.Ketf.GetWebappHash جهت دریافت هش رمزی اختصاصی ربات برای تایید کاربر:
const hashInfo = await client.getWebappHash(botId, 'custom_payload');
console.log('هش امنیتی:', hashInfo.hash);
console.log('شناسه کوئری:', hashInfo.queryId);
console.log('تاریخ احراز هویت:', hashInfo.authDate);
ارسال داده از مینیاپ به ربات (sendMiniAppData)
رویداد sendData برای ارسال نتیجه تراکنش یا امتیاز از مینیاپ به ربات:
await client.sendMiniAppData({
botUserId: botId,
queryId: hashInfo.queryId,
data: { score: 150, action: 'game_finished' },
buttonText: 'تایید و ادامه'
});
console.log('دادههای وباپ با موفقیت به ربات ارسال شد.');
بازوهای رسمی بله (Bale HTTP Bot API - docs.bale.ai)
پشتیبانی کامل و استاندارد بدون نیاز به پیشنیازهای سنگین از API رسمی بازوهای بله (docs.bale.ai). این کلاس به شما امکان میدهد رباتهای رسمی با توکن دریافتی از @botfather در بله بسازید، رویدادها را دریافت کرده و انواع پیامها، کیبوردها و فاکتورهای پرداخت الکترونیکی را مدیریت کنید.
برای شروع، وارد پیامرسان بله شده و به بازوی رسمی @botfather پیام دهید. پس از ایجاد بازو، یک توکن اختصاصی شبیه به 123456789:abcdIuZmK5qNEm2A1BhUaAg7MPJv1O9KCcBQB2ro دریافت میکنید.
آدرس فراخوانی متدها: https://tapi.bale.ai/bot<token>/<methodName>
آدرس دانلود فایلها: https://tapi.bale.ai/file/bot<token>/<file_path>
const { BaleBot, InlineKeyboard, ReplyKeyboard } = require('balex');
// ۱. مقداردهی کلاینت با توکن باتفادر بله
const bot = new BaleBot('123456789:abcdIuZmK5qNEm2A1BhUaAg7MPJv1O9KCcBQB2ro');
// ۲. بررسی صحت توکن و دریافت مشخصات ربات
const me = await bot.getMe();
console.log('ربات فعال شد: @' + me.username + ' (' + me.first_name + ')');
// ۳. لیسنر دریافت پیامهای متنی و دستورات
bot.on('message', async (msg) => {
if (msg.text === '/start') {
const kb = new InlineKeyboard()
.button('ثبتنام', 'btn_register')
.url('وبسایت بله', 'https://ble.ir')
.row()
.webApp('اجرای مینیاپ', 'https://miniapp.example.com')
.copyText('کپی کد تخفیف', 'DISCOUNT2026');
await bot.sendMessage(msg.chat.id, 'سلام! به بازوی رسمی بله خوش آمدید.', {
reply_markup: kb
});
}
});
// ۴. شروع دریافت آپدیتها با Long Polling
bot.startPolling({ interval: 300, timeout: 20 });
ساختار انواع دادهای و اشیاء بازوی بله (Bale Types & Schemas)
پلتفرم بازوی بله بر پایه ساختارهای دادهای استاندارد JSON طراحی شده است. کلاس BaleBot تمامی این تایپها را به صورت آبجکتهای تایپشده در TypeScript با اتوکامپلیت کامل به شما ارائه میدهد:
| نوع دادهای (Type) | فیلدهای اصلی | توضیحات و کاربرد |
|---|---|---|
User |
id, is_bot, first_name, last_name, username |
نمایش یک حساب کاربری یا حساب ربات در بله. |
Chat |
id, type ("private" | "group" | "channel"), title, username, first_name, last_name |
اطلاعات گفتگوی خصوصی، گروه یا کانال. |
ChatFullInfo |
id, type, title, description, invite_link, pinned_message, permissions, photo |
اطلاعات جامع و تفصیلی چت بازگشتی از متد getChat. |
Message |
message_id, from, date, chat, forward_from, reply_to_message, text, entities, photo, video, audio, voice, document, animation, contact, location, invoice, successful_payment |
آبجکت اصلی پیام دریافتی یا ارسالی با تمامی ویژگیهای رسانهای و فرادادهای. |
MessageEntity |
type, offset, length, url, user |
موجودیت قالببندی درون متن (مانند bold, italic, code, text_link, mention, hashtag). |
PhotoSize |
file_id, file_unique_id, width, height, file_size |
اندازههای مختلف تصویر پیشنمایش در بله. |
Audio / Video / Voice / Document |
file_id, duration, mime_type, file_size, thumb, file_name, performer, title |
ساختارهای فایلهای چندرسانهای ذخیرهشده روی CDN بله. |
Contact |
phone_number, first_name, last_name, user_id, vcard |
اطلاعات کارت مخاطب اشتراکگذاری شده. |
Location |
latitude, longitude, horizontal_accuracy, live_period |
مختصات جغرافیایی ارسالشده توسط کاربر. |
Invoice |
title, description, start_parameter, currency, total_amount |
اطلاعات فاکتور پرداخت ارسالی برای کاربر. |
PreCheckoutQuery |
id, from, currency, total_amount, invoice_payload |
درخواست پیشتایید پرداخت که باید توسط ربات ظرف ۱۰ ثانیه پاسخ داده شود. |
SuccessfulPayment |
currency, total_amount, invoice_payload, provider_payment_charge_id |
تاییدیه پرداخت نهایی موفق کاربر. |
ChatMember |
status, user, custom_title, can_be_edited, can_manage_chat, can_delete_messages |
وضعیت و سطح دسترسی کاربر در گروه یا کانال (owner, administrator, member, restricted, left, kicked). |
WebhookInfo |
url, has_custom_certificate, pending_update_count, last_error_date, last_error_message |
وضعیت جاری سرویس وبهوک تنظیمشده برای بازو. |
ResponseParameters |
migrate_to_chat_id, retry_after |
پارامترهای کمکی هنگام مواجهه با جابجایی چت یا محدودیت نرخ ارسال (Rate Limit). |
فرمتبندی پیشرفته متن و موجودیتها (Formatting & Markdown/HTML)
پلتفرم بازوی بله از دو فرمت محبوب HTML و Markdown برای برجستهسازی، درج لینک، و قالببندی متون پیامها و کپشنهای رسانه پشتیبانی میکند.
| قالب (Style) | سینتکس HTML (پیشنهادی) | سینتکس Markdown | نتیجه نمایشی |
|---|---|---|---|
| متن پررنگ (Bold) | <b>متن</b> یا <strong>متن</strong> |
*متن* |
متن پررنگ |
| متن کج (Italic) | <i>متن</i> یا <em>متن</em> |
_متن_ |
متن کج |
| کد درونخطی (Code) | <code>const x = 1;</code> |
`const x = 1;` |
const x = 1; |
| بلوک کد چندخطی (Pre) | <pre>کد برنامه</pre> |
```کد برنامه``` |
بلوک کد مونواسپیس |
| لینک متنی (Link) | <a href="https://ble.ir">بله</a> |
[بله](https://ble.ir) |
بله |
| خطخورده (Strikethrough) | <s>تخفیف منقضی</s> |
~تخفیف منقضی~ |
|
| زیرخطدار (Underline) | <u>توجه مهم</u> |
- | توجه مهم |
// روش ۱: ارسال پیام با حالت HTML
const htmlText = '📢 اطلاعیه مهم نسخه ۱.۲.۰
' +
'امکانات جدید اضافه شد:
' +
'• BaleBot: پشتیبانی کامل از docs.bale.ai
' +
'• سرعت بالا و بدون وابستگی
' +
'جهت اطلاعات بیشتر به وبسایت بله مراجعه کنید.';
await bot.sendMessage(chatId, htmlText, { parse_mode: 'HTML' });
// روش ۲: ارسال پیام با آرایه مستقیم entities (بدون نیاز به اسکیپ کاراکترها)
await bot.sendMessage(chatId, 'کلیک کنید: پشتیبانی بله', {
entities: [
{ type: 'bold', offset: 0, length: 11 },
{ type: 'text_link', offset: 12, length: 13, url: 'https://ble.ir/support' }
]
});
دریافت آپدیتها (Long Polling & Webhook)
بازوی بله از دو شیوه استاندارد برای تحویل رویدادهای زنده کاربران بهره میبرد:
// ۱. شیوه لانگ پولینگ (مناسب سیستمهای تست و سرورهای بدون دامنه عمومی)
bot.startPolling({
interval: 300, // فاصله بررسی میلیثانیه
timeout: 25, // نگهداشتن اتصال لانگ پولینگ در سرور بله (ثانیه)
limit: 100 // حداکثر آپدیت در هر درخواست
});
// توقف پولینگ در زمان خاموش شدن برنامه
process.on('SIGINT', () => {
bot.stopPolling();
process.exit(0);
});
// ۲. شیوه وبهوک (مناسب سرورهای توزیعشده با دامنه HTTPS)
await bot.setWebhook('https://bot.example.com/bale-webhook');
// بررسی وضعیت وبهوک فعال
const hookInfo = await bot.getWebhookInfo();
console.log('وضعیت وبهوک:', hookInfo.url, 'آپدیتهای معلق:', hookInfo.pending_update_count);
// میدلور آماده وبهوک سازگار با Express / Node http
const http = require('http');
const webhookHandler = bot.createWebhookMiddleware({ secretToken: 'SUPER_SECRET_123' });
http.createServer((req, res) => {
if (req.url === '/bale-webhook') return webhookHandler(req, res);
res.writeHead(404).end();
}).listen(8443);
// ۳. لیسنرهای رویدادهای مختلف
bot.on('message', (msg) => console.log('پیام جدید:', msg.text));
bot.on('edited_message', (msg) => console.log('پیام ویرایش شد:', msg.message_id));
bot.on('callback_query', (cb) => console.log('کلیک دکمه اینلاین:', cb.data));
bot.on('pre_checkout_query', (pcq) => console.log('تایید پرداخت:', pcq.id));
bot.on('successful_payment', (pay, msg) => console.log('پرداخت موفق:', pay.total_amount));
bot.on('error', (err) => console.error('خطای بازو:', err.message));
ارسال انواع فایل و رسانهها (Media API & File Uploads)
کتابخانه BaleX از ۴ روش مختلف برای ارسال فایل پشتیبانی میکند: شناسه file_id، آدرس اینترنتی URL، مسیر فایل محلی string، و شیء بافر حافظه Buffer.
const fs = require('fs');
// ۱. ارسال عکس (با ۴ روش تامین منبع فایل)
// الف) با شناسه قبلی موجود در بله (سریعترین روش بدون مصرف پهنای باند)
await bot.sendPhoto(chatId, '123456789:photo_file_id_here', { caption: 'عکس از آرشیو بله' });
// ب) با لینک مستقیم اینترنتی
await bot.sendPhoto(chatId, 'https://example.com/banner.jpg', { caption: 'دانلود مستقیم توسط سرور بله' });
// ج) با آدرس فایل محلی (آپلود خودکار به صورت multipart/form-data)
await bot.sendPhoto(chatId, './assets/logo.png', { caption: 'آپلود لوگو محلی' });
// د) با بافر حافظه
const imageBuffer = fs.readFileSync('./assets/chart.png');
await bot.sendPhoto(chatId, imageBuffer, { caption: 'نمودار تولیدی لحظهای' });
// ۲. ارسال موزیک و فایل صوتی (Audio)
await bot.sendAudio(chatId, './music/track.mp3', {
caption: 'پادکست شماره ۱',
performer: 'تیم بله',
title: 'مصاحبه اختصاصی',
duration: 180
});
// ۳. ارسال سند و فایل فشرده (Document)
await bot.sendDocument(chatId, './files/report.pdf', {
caption: 'گزارش مالی سالانه'
});
// ۴. ارسال ویدیو (Video)
await bot.sendVideo(chatId, './videos/tutorial.mp4', {
caption: 'آموزش ویدیویی کار با بازو',
duration: 65,
width: 1280,
height: 720
});
// ۵. ارسال گیف و انیمیشن (Animation)
await bot.sendAnimation(chatId, './animations/celebrate.gif', {
caption: 'تبریک سال نو!'
});
// ۶. ارسال پیام صوتی و ویس (Voice)
await bot.sendVoice(chatId, './voices/note.ogg', {
duration: 12
});
// ۷. ارسال آلبوم رسانهای (Media Group)
await bot.sendMediaGroup(chatId, [
{ type: 'photo', media: './photo1.jpg', caption: 'تصویر اول' },
{ type: 'photo', media: './photo2.jpg' },
{ type: 'video', media: './clip.mp4', caption: 'ویدیوی همراه' }
]);
// ۸. ارسال موقعیت جغرافیایی و لوکیشن زنده (Location)
await bot.sendLocation(chatId, 35.7219, 51.3347, {
horizontal_accuracy: 15
});
// ۹. ارسال مخاطب (Contact)
await bot.sendContact(chatId, '+989123456789', 'پشتیبانی', {
last_name: 'فنی'
});
// ۱۰. ارسال وضعیت در حال انجام کار (Chat Action)
await bot.sendChatAction(chatId, 'upload_photo');
// ۱۱. دریافت اطلاعات فایل و دانلود مستقیم از سرور بله
const fileInfo = await bot.getFile('file_id_here');
console.log('آدرس فایل روی CDN بله:', fileInfo.file_path);
const buffer = await bot.downloadFile(fileInfo.file_path, './downloaded_file.png');
دکمههای شیشهای، کیبوردهای معمولی و مینیاپها (Keyboards)
کلاسهای کاربردی InlineKeyboard و ReplyKeyboard پیادهسازی رابطهای کاربری تعاملی را بسیار ساده و روان کردهاند:
// ۱. کیبورد شیشهای (InlineKeyboard)
const inlineKb = new InlineKeyboard()
.button('تایید و ثبت سفارش', 'order_confirm_44')
.button('انصراف', 'order_cancel')
.row()
.url('مشاهده جزئیات در کانال', 'https://ble.ir/bale')
.row()
.webApp('باز کردن مینیاپ فروشگاه', 'https://shop.example.com')
.copyText('کپی کد معرف', 'REF_998811'); // کپی سریع متن در کلیپبورد کاربر
await bot.sendMessage(chatId, 'لطفاً وضعیت سفارش را تعیین کنید:', {
reply_markup: inlineKb
});
// ۲. پاسخدهی به کلیک دکمه شیشهای (answerCallbackQuery)
bot.on('callback_query', async (query) => {
if (query.data === 'order_confirm_44') {
// ارسال آلرت پاپآپ روی صفحه کاربر
await bot.answerCallbackQuery(query.id, {
text: 'سفارش شما با موفقیت ثبت شد!',
show_alert: true
});
} else {
// پیام ناتیفیکیشن کوچک بالای صفحه
await bot.answerCallbackQuery(query.id, { text: 'عملیات لغو شد.' });
}
});
// ۳. کیبورد معمولی چت (ReplyKeyboard) با درخواست شماره و لوکیشن
const replyKb = new ReplyKeyboard({ resize: true, oneTime: true })
.button('منوی اصلی')
.button('مشاهده صورتحساب')
.row()
.requestContact('ارسال شماره تلفن همراه 📱')
.requestLocation('ارسال لوکیشن تحویل 📍');
await bot.sendMessage(chatId, 'برای احراز هویت شماره یا لوکیشن خود را بفرستید:', {
reply_markup: replyKb
});
// ۴. حذف کیبورد معمولی با KeyboardRemove
const { KeyboardRemove } = require('balex');
await bot.sendMessage(chatId, 'کیبورد مخفی شد.', {
reply_markup: new KeyboardRemove()
});
مدیریت کامل چتها، گروهها و اعضا (Chat Administration)
مجموعه کامل متدهای مدیریتی برای اخراج، ارتقای مدیران، تنظیم اطلاعات و لینکهای دعوت در گروهها و کانالهای بله:
// ۱. دریافت اطلاعات کامل چت یا گروه
const chatInfo = await bot.getChat(groupId);
console.log('عنوان گروه:', chatInfo.title, 'توضیحات:', chatInfo.description);
// ۲. تعداد اعضا و لیست مدیران چت
const count = await bot.getChatMembersCount(groupId);
const admins = await bot.getChatAdministrators(groupId);
console.log('تعداد اعضا: ' + count + ' | تعداد مدیران: ' + admins.length);
// ۳. استعلام وضعیت یک عضو در چت
const member = await bot.getChatMember(groupId, targetUserId);
console.log('نقش کاربر:', member.status); // creator, administrator, member, restricted
// ۴. مسدودسازی و اخراج کاربر از گروه (Ban)
await bot.banChatMember(groupId, targetUserId);
// ۵. رفع مسدودیت کاربر (Unban)
await bot.unbanChatMember(groupId, targetUserId);
// ۶. ارتقای کاربر به سطح مدیر با تعیین دسترسیها (Promote)
await bot.promoteChatMember(groupId, targetUserId, {
can_change_info: true,
can_delete_messages: true,
can_invite_users: true,
can_pin_messages: true
});
// ۷. تغییر مشخصات گروه (عکس، عنوان، توضیحات)
await bot.setChatTitle(groupId, 'انجمن برنامهنویسان بله 🚀');
await bot.setChatDescription(groupId, 'گفتگو پیرامون توسعه بازوها و مینیاپهای بله');
await bot.setChatPhoto(groupId, './assets/group_avatar.png');
// await bot.deleteChatPhoto(groupId); // حذف عکس فعلی گروه
// ۸. پین کردن و برداشتن پین پیامها
await bot.pinChatMessage(groupId, messageId);
await bot.unpinChatMessage(groupId, messageId);
await bot.unpinAllChatMessages(groupId); // حذف همه پینها
// ۹. ایجاد و باطلسازی لینک دعوت به چت
const invite = await bot.createChatInviteLink(groupId);
console.log('لینک دعوت جدید:', invite.invite_link);
await bot.revokeChatInviteLink(groupId, invite.invite_link);
// ۱۰. خروج بازو از گروه یا کانال
await bot.leaveChat(groupId);
ویرایش، حذف، فوروارد و پاپآپ نظرخواهی بله (Messages & askReview)
عملیات روی پیامهای ارسالشده و متد اختصاصی پلتفرم بله برای ثبت امتیاز کاربر:
// ۱. ویرایش متن پیام ارسال شده
await bot.editMessageText(chatId, messageId, 'این متن با موفقیت ویرایش شد! ✏️', {
parse_mode: 'HTML'
});
// ۲. ویرایش کپشن رسانه
await bot.editMessageCaption(chatId, messageId, 'کپشن جدید ویدیو');
// ۳. ویرایش دکمههای شیشهای زیر پیام
const newKb = new InlineKeyboard().button('دکمه جدید', 'btn_updated');
await bot.editMessageReplyMarkup(chatId, messageId, newKb);
// ۴. حذف تکی یا گروهی پیامها
await bot.deleteMessage(chatId, messageId);
await bot.deleteMessages(chatId, [msgId1, msgId2, msgId3]);
// ۵. فوروارد و کپی پیام
await bot.forwardMessage(targetChatId, fromChatId, messageId);
await bot.copyMessage(targetChatId, fromChatId, messageId, { caption: 'کپی بدون تگ فوروارد' });
// ۶. متد اختصاصی بله: درخواست ثبت نظر و امتیاز کاربر (askReview)
// این متد یک دیالوگ بومی ۵ ستاره در کلاینت کاربر بله باز میکند تا به بازوی شما امتیاز دهد!
await bot.askReview(chatId);
console.log('دیالوگ ثبت امتیاز بومی بله برای کاربر نمایش داده شد.');
ساخت و مدیریت بستههای استیکر (Stickers API)
بازوهای بله امکان ساخت، آپلود و اضافه کردن استیکرهای اختصاصی را با فایلهای PNG سایز ۵۱۲x۵۱۲ پیکسل دارند:
// ۱. آپلود فایل استیکر PNG با سایز ۵۱۲x۵۱۲
const stickerFile = await bot.uploadStickerFile(userId, './stickers/emoji1.png');
console.log('فایل استیکر آپلود شد:', stickerFile.file_id);
// ۲. ساخت بسته استیکر جدید
await bot.createNewStickerSet(
userId,
'my_cool_stickers_by_mybot',
'استیکرهای اختصاصی بازو',
'./stickers/emoji1.png',
'🔥'
);
// ۳. افزودن استیکر جدید به بسته موجود
await bot.addStickerToSet(
userId,
'my_cool_stickers_by_mybot',
'./stickers/emoji2.png',
'🚀'
);
پرداخت و کیفپول الکترونیکی بله (Electronic Wallet & Invoices)
پلتفرم مالی بله امکان صدور فاکتور ریالی مستقیم و کسر وجه از کیفپول یا درگاه شتابی را فراهم میکند:
// ۱. ارسال فاکتور پرداخت درون چت
await bot.sendInvoice(
chatId,
'اشتراک طلایی ۱ ماهه',
'دسترسی نامحدود به تمامی امکانات ویژه بازو',
'order_payload_10023',
'PROVIDER_TOKEN_HERE',
'IRR',
[
{ label: 'مبلغ پلن', amount: 500000 },
{ label: 'تخفیف عیدانه', amount: -50000 }
],
{
photo_url: 'https://example.com/gold.jpg',
need_phone_number: true
}
);
// ۲. ساخت لینک مستقیم پرداخت بدون پیام
const payLink = await bot.createInvoiceLink(
'خرید جم بازی',
'۱۰۰۰ جم الماس',
'gem_purchase_88',
'PROVIDER_TOKEN_HERE',
'IRR',
[{ label: 'قیمت جم', amount: 150000 }]
);
console.log('لینک پرداخت مستقیم:', payLink);
// ۳. پاسخدهی به تایید اولیه خرید (PreCheckoutQuery) ظرف ۱۰ ثانیه
bot.on('pre_checkout_query', async (query) => {
console.log('درخواست خرید از کاربر:', query.from.id, 'مبلغ:', query.total_amount);
// موجودی انبار را چک میکنیم و تایید میکنیم:
await bot.answerPreCheckoutQuery(query.id, true);
});
// ۴. دریافت نوتیفیکیشن پرداخت نهایی موفق
bot.on('successful_payment', async (payment, msg) => {
console.log('✅ پرداخت ' + payment.total_amount + ' ریال با شناسه پیگیری ' + payment.provider_payment_charge_id + ' انجام شد.');
await bot.sendMessage(msg.chat.id, 'پرداخت شما با موفقیت تایید شد! اشتراک شما فعال گردید.');
});
// ۵. استعلام مستقل وضعیت یک تراکنش بانکی با شناسه
const tx = await bot.inquireTransaction('transaction_id_9988');
console.log('وضعیت تراکنش:', tx.status, 'مبلغ نهایی:', tx.amount);
جدول خطاهای HTTP Bot API و راهنمای عیبیابی (Bot Error Codes)
هنگام بروز خطا در فراخوانی متدهای بازو، شیء خطای Error همراه با کدهای وضعیت استاندارد و توضیحات فارسی/انگلیسی بازگردانده میشود:
| کد وضعیت HTTP | نوع خطا | علت احتمالی در بله | راهکار رفع مشکل |
|---|---|---|---|
400 |
Bad Request | پارامترهای ارسالی نامعتبر، خالی بودن متن پیام، چت نامعتبر، یا خطای سینتکس Markdown/HTML. | بررسی فرمت متن ارسالی یا استفاده از parse_mode: 'HTML' به جای Markdown. |
401 |
Unauthorized | توکن بازو نامعتبر است یا توسط باتفادر باطل شده است. | توکن دریافتی از @botfather را بازبینی کنید. |
403 |
Forbidden | کاربر بازو را مسدود کرده است یا بازو از گروه اخراج شده و مجوز ارسال ندارد. | بررسی دسترسیهای بازو در گروه یا توقف ارسال به کاربر مسدودکننده. |
404 |
Not Found | پیام، چت، یا متد درخواستی یافت نشد. | بررسی chat_id و message_id های ارسالی. |
429 |
Too Many Requests | تجاوز از سقف مجاز ارسال پیام (Rate Limit). آبجکت خطا شامل err.parameters.retry_after است. |
به مدت مشخص شده در retry_after ثانیه منتظر بمانید و سپس درخواست را تکرار کنید. |
500 / 502 |
Server Error | خطای موقت در سرورهای بله یا قطعی ارتباط با دیتابیس بله. | از سیستم تلاش مجدد خودکار (Retry with Exponential Backoff) استفاده کنید. |
کاتالوگ جامع تمامی ۶۲ متد رسمی بازوی بله (docs.bale.ai)
تمامی متدهای استاندارد پلتفرم بات بله در کلاس BaleBot با امضاهای دقیق، گزینهها و تایپهای بازگشتی پیادهسازی شدهاند:
| دستهبندی | نام متد و پارامترها | نوع بازگشتی | توضیحات عملکرد |
|---|---|---|---|
| چرخه حیات | bot.getMe() | Promise<User> | دریافت اطلاعات حساب ربات (نام کاربری، نام، شناسه). |
| چرخه حیات | bot.logout() | Promise<boolean> | خروج از توکن و باطلسازی سشن فعلی ربات. |
| چرخه حیات | bot.close() | Promise<boolean> | بستن پردازش بات و لغو درخواستهای باز. |
| آپدیتها | bot.getUpdates(options) | Promise<Update[]> | دریافت دستی آرایه آپدیتها با offset و limit. |
| وبهوک | bot.setWebhook(urlOrOptions) | Promise<boolean> | تنظیم آدرس URL وبهوک و توکن امنیتی در سرور بله. |
| وبهوک | bot.deleteWebhook() | Promise<boolean> | حذف آدرس وبهوک و بازگشت به حالت Polling. |
| وبهوک | bot.getWebhookInfo() | Promise<WebhookInfo> | استعلام وضعیت جاری وبهوک، خطاهای اخیر و اتصالات معلق. |
| میدلور | bot.createWebhookMiddleware(opts) | Function(req, res) | میدلور پردازش وبهوک سازگار با Express و Node http. |
| پولینگ | bot.startPolling(options) | void | شروع دریافت خودکار آپدیتها با متد Long Polling. |
| پولینگ | bot.stopPolling() | void | توقف دریافت آپدیتها و لغو تایمرهای پولینگ. |
| پیام متنی | bot.sendMessage(chatId, text, opts) | Promise<Message> | ارسال پیام متنی با پشتیبانی از Markdown، HTML و کیبورد. |
| فوروارد | bot.forwardMessage(chatId, fromChatId, msgId) | Promise<Message> | فوروارد پیام با حفظ نام ارسالکننده اصلی. |
| کپی پیام | bot.copyMessage(chatId, fromChatId, msgId, opts) | Promise<{message_id}> | کپی پیام بدون برچسب فوروارد. |
| عکس | bot.sendPhoto(chatId, photo, opts) | Promise<Message> | ارسال عکس از طریق file_id، URL، مسیر فایل یا Buffer. |
| صدا | bot.sendAudio(chatId, audio, opts) | Promise<Message> | ارسال فایل صوتی و موسیقی با مشخصات خواننده و عنوان. |
| سند و فایل | bot.sendDocument(chatId, doc, opts) | Promise<Message> | ارسال هرگونه فایل، اسناد PDF، Zip و دادهها. |
| ویدیو | bot.sendVideo(chatId, video, opts) | Promise<Message> | ارسال ویدیو همراه با ابعاد و مدت زمان. |
| گیف | bot.sendAnimation(chatId, anim, opts) | Promise<Message> | ارسال انیمیشن و گیف متحرک. |
| ویس | bot.sendVoice(chatId, voice, opts) | Promise<Message> | ارسال پیام صوتی (Voice note) فرمت OGG/Opus. |
| آلبوم | bot.sendMediaGroup(chatId, media) | Promise<Message[]> | ارسال آلبوم رسانهای متشکل از ۲ الی ۱۰ تصویر یا ویدیو. |
| لوکیشن | bot.sendLocation(chatId, lat, lon, opts) | Promise<Message> | ارسال موقعیت جغرافیایی روی نقشه. |
| مخاطب | bot.sendContact(chatId, phone, name, opts) | Promise<Message> | اشتراکگذاری اطلاعات شماره تلفن و کارت مخاطب. |
| وضعیت کار | bot.sendChatAction(chatId, action) | Promise<boolean> | نمایش وضعیت typing، upload_photo و غیره در هدر چت. |
| دانلود فایل | bot.getFile(fileId) | Promise<File> | دریافت مسیر فایل و حجم آن جهت دانلود از سرور بله. |
| دانلود فایل | bot.downloadFile(fileIdOrPath, dest) | Promise<Buffer|string> | دانلود مستقیم باینری فایل از بله و ذخیره در مسیر دلخواه. |
| دکمه شیشهای | bot.answerCallbackQuery(id, opts) | Promise<boolean> | پاسخ به کلیک دکمه اینلاین با پیام ناتیفیکیشن یا آلرت پاپآپ. |
| اختصاصی بله | bot.askReview(chatId) | Promise<boolean> | باز کردن پنجره دیالوگ بومی ثبت نظر و امتیاز کاربر در بله. |
| ویرایش | bot.editMessageText(chatId, msgId, text, opts) | Promise<Message> | ویرایش متن پیام ارسالشده قبلی. |
| ویرایش | bot.editMessageCaption(chatId, msgId, cap, opts) | Promise<Message> | ویرایش کپشن تصویر یا رسانه ارسالشده. |
| ویرایش | bot.editMessageReplyMarkup(chatId, msgId, kb) | Promise<Message> | تغییر یا حذف کیبورد شیشهای زیر پیام. |
| حذف پیام | bot.deleteMessage(chatId, messageId) | Promise<boolean> | حذف یک پیام در گفتگو یا گروه. |
| حذف گروهی | bot.deleteMessages(chatId, messageIds) | Promise<boolean> | حذف همزمان چندین پیام با شناسه آرایهای. |
| مدیریت چت | bot.banChatMember(chatId, userId) | Promise<boolean> | مسدودسازی و اخراج عضو از گروه یا کانال. |
| مدیریت چت | bot.unbanChatMember(chatId, userId) | Promise<boolean> | رفع مسدودیت عضو اخراجشده قبلی. |
| مدیریت چت | bot.promoteChatMember(chatId, userId, opts) | Promise<boolean> | ارتقای سطح کاربر به مدیر گروه و تفویض اختیارات. |
| اطلاعات | bot.getChat(chatId) | Promise<ChatFullInfo> | دریافت اطلاعات جامع چت، گروه یا کانال. |
| اطلاعات | bot.getChatAdministrators(chatId) | Promise<ChatMember[]> | دریافت لیست مدیران و اختیارات تفویض شده. |
| اطلاعات | bot.getChatMembersCount(chatId) | Promise<number> | تعداد کل اعضای گروه یا کانال. |
| اطلاعات | bot.getChatMember(chatId, userId) | Promise<ChatMember> | استعلام رتبه و وضعیت یک عضو در چت. |
| تنظیمات چت | bot.setChatPhoto(chatId, photo) | Promise<boolean> | تنظیم یا تعویض عکس نمایه گروه یا کانال. |
| تنظیمات چت | bot.deleteChatPhoto(chatId) | Promise<boolean> | حذف عکس پروفایل فعلی گروه یا کانال. |
| تنظیمات چت | bot.setChatTitle(chatId, title) | Promise<boolean> | تغییر عنوان گروه یا کانال. |
| تنظیمات چت | bot.setChatDescription(chatId, desc) | Promise<boolean> | تغییر بیوگرافی و توضیحات گروه. |
| پین پیام | bot.pinChatMessage(chatId, messageId) | Promise<boolean> | سنجاق کردن پیام در بالای گروه یا کانال. |
| برداشتن پین | bot.unpinChatMessage(chatId, messageId) | Promise<boolean> | برداشتن سنجاق یک پیام خاص. |
| برداشتن پین | bot.unPinChatMessage(chatId, messageId) | Promise<boolean> | نام مستعار سازگار با استایل کملکیس docs.bale.ai. |
| برداشتن پین | bot.unpinAllChatMessages(chatId) | Promise<boolean> | پاکسازی کامل همه پیامهای سنجاقشده در چت. |
| خروج | bot.leaveChat(chatId) | Promise<boolean> | خروج بازو از یک گروه یا کانال. |
| لینک دعوت | bot.createChatInviteLink(chatId) | Promise<ChatInviteLink> | ایجاد لینک دعوت جدید برای گروه یا کانال. |
| لینک دعوت | bot.revokeChatInviteLink(chatId, link) | Promise<ChatInviteLink> | باطلسازی لینک دعوت فعال قبلی. |
| لینک دعوت | bot.exportChatInviteLink(chatId) | Promise<string> | استخراج لینک اصلی دعوت به گروه. |
| استیکر | bot.uploadStickerFile(userId, png) | Promise<File> | آپلود فایل استیکر PNG با سایز ۵۱۲x۵۱۲. |
| استیکر | bot.createNewStickerSet(userId, name, title, png, emojis) | Promise<boolean> | ساخت بسته استیکر جدید برای ربات. |
| استیکر | bot.addStickerToSet(userId, name, png, emojis) | Promise<boolean> | افزودن استیکر جدید به بسته موجود. |
| پرداخت بله | bot.sendInvoice(chatId, title, desc, payload, token, curr, prices, opts) | Promise<Message> | ارسال فاکتور خرید کیفپول الکترونیکی بله با مبلغ ریالی. |
| پرداخت بله | bot.createInvoiceLink(title, desc, payload, token, curr, prices, opts) | Promise<string> | ساخت لینک مستقیم پرداخت بدون نیاز به ارسال پیام. |
| پرداخت بله | bot.answerPreCheckoutQuery(queryId, ok, errMsg) | Promise<boolean> | تایید نهایی وضعیت کالا ظرف ۱۰ ثانیه پیش از کسر وجه. |
| پرداخت بله | bot.inquireTransaction(transactionId) | Promise<Transaction> | استعلام وضعیت موفقیت، مبلغ و زمان تراکنش بانکی. |
| عمومی | bot.call(method, params, files) | Promise<any> | ارسال مستقیم هر درخواست سفارشی به پلتفرم HTTP بله. |
| عمومی | bot.getMethodUrl(method) | string | تولید آدرس کامل متد همراه با توکن. |
| عمومی | bot.getFileUrl(filePath) | string | تولید آدرس دانلود مستقیم فایل روی سرور بله. |
استوریهای بله (Stories API)
سرویس bale.story.v1.Story برای ارسال، مشاهده و تعامل با استوریها:
// ۱. انتشار استوری جدید
await client.sendStory({
caption: 'روز زیبای بهاری 🌿'
});
// ۲. مشاهده استوریهای فعال کاربر یا چت
const stories = await client.getUserStories(123456789);
console.log('استوریها:', stories);
// ۳. مشاهده بینندگان استوری
const viewers = await client.getStoryViewers(stories[0]?.storyId);
console.log('بینندگان استوری:', viewers);
// ۴. لایک کردن استوری
await client.likeStory(stories[0]?.storyId, '🔥');
// ۵. حذف استوری
await client.deleteStory(stories[0]?.storyId);
پیامهای زمانبندی شده (Scheduled Messages)
ارسال پیام در تاریخ و زمان مشخص در آینده (سرویس bale.schedule.v1.Scheduler):
// تنظیم ارسال پیام برای ۲ ساعت بعد
const sendTime = Date.now() + (2 * 60 * 60 * 1000);
await client.scheduleMessage({
peer: 123456789,
text: 'یادآوری: جلسه هفتگی آغاز شد!',
sendAtDate: sendTime
});
// دریافت لیست پیامهای زمانبندیشده
const tasks = await client.loadScheduledMessages(123456789);
console.log('پیامهای زمانبندیشده:', tasks);
// لغو یک پیام زمانبندی شده
await client.deleteScheduledMessage(123456789, tasks[0]?.taskId);
هوش مصنوعی و خلاصهساز بله (AI & TLDR)
استفاده از هوش مصنوعی تورینگ و موتور خلاصهساز بله:
// ۱. خلاصهسازی یک لینک یا صفحه با Bale TLDR
const summary = await client.summarizeLink('https://bale.ai');
console.log('خلاصه محتوا:', summary);
// ۲. پرسش از هوش مصنوعی تورینگ بله
const aiAnswer = await client.askAI('ساعت کاری شعب بانک در تعطیلات چگونه است؟');
console.log('پاسخ هوش مصنوعی:', aiAnswer);
بانکداری و خدمات مالی شتابی
استعلام نام صاحب کارت شتابی (inquireDestinationPan)
استعلام نام و نام خانوادگی دارنده حساب کارت مقصد قبل از واریز وجه:
const inquiry = await client.inquireDestinationPan({
sourceCardNumber: '6037991812345678', // ۱۶ رقم کارت مبدا
destinationCardNumber: '5022291087654321', // ۱۶ رقم کارت مقصد
amountRials: '10000000' // مبلغ (ریال)
});
console.log('صاحب کارت مقصد:', inquiry.fullName);
console.log('نام بانک مقصد:', inquiry.bankName);
console.log('توکن تایید انتقال:', inquiry.inquiryToken);
انتقال وجه کارت به کارت شتابی (transferMoneyByCard)
انجام تراکنش مستقیم کارت به کارت با رمز دوم پویا (OTP):
const receipt = await client.transferMoneyByCard({
sourcePan: '6037991812345678',
destinationPan: '5022291087654321',
amountRials: '10000000',
cvv2: '345',
expireDate: '0628', // ماه و سال (۲ رقم ماه + ۲ رقم سال)
pin2: '984512', // رمز دوم یکبار مصرف پیامکشده
inquiryToken: inquiry.inquiryToken,
description: 'پرداخت فاکتور خرید'
});
console.log('کد پیگیری شتاب:', receipt.trackingCode);
console.log('شماره ارجاع شاپرک (RRN):', receipt.rrn);
استعلام موجودی کارت شتابی (getCardBalance)
const balance = await client.getCardBalance({
sourcePan: '6037991812345678',
pin2: '984512',
cvv2: '345',
expireDate: '0628'
});
console.log('موجودی کارت:', balance.balanceRials, 'ریال');
console.log('موجودی قابل برداشت:', balance.availableBalanceRials, 'ریال');
ارسال پاکت هدیه طلای بله (sendGoldPacket)
ارسال هدیه شمش طلا بر حسب میلیگرم در چت:
await client.sendGoldPacket({
peerId: 123456789,
goldMilligrams: 100, // ۱۰۰ میلیگرم طلا
message: 'تبریک روز مهندس از طرف BaleX! 🎁',
packetType: 0
});
console.log('پاکت طلایی با موفقیت ارسال شد.');
موتور حضور و ضد مسدودی (Presence & Stealth)
کنترل وضعیت آنلاین و تایپینگ (setOnline / sendTyping / stopTyping)
// ۱. ارسال وضعیت آنلاین (سبز شدن چراغ آنلاین در بله)
await client.setOnline(true);
// ۲. ارسال وضعیت "در حال نوشتن..." با توقف خودکار بعد از ۳ ثانیه
await client.sendTyping(peerId, 3000);
// ۳. توقف دستی تایپ
await client.stopTyping(peerId);
تنظیمات موتور ضد مسدودی در حین اجرا (Humanize Controls)
// فعالسازی حالت انسانی با تنظیمات اختصاصی
client.enableHumanize({
readDelay: [800, 2000], // تاخیر خواندن پیام بین ۸۰۰ تا ۲۰۰۰ میلیثانیه
typingDurationPerChar: 40, // ۴۰ میلیثانیه تایپ به ازای هر حرف
minTypingDelay: 1000,
maxTypingDelay: 7000,
autoMarkAsRead: true, // سین خودکار پیام قبل از پاسخ
keepOnline: true // ارسال هارتبیت آنلاین ماندن
});
// تغییر داینامیک و پویا در حین اجرای برنامه با متد setHumanize:
client.setHumanize({
readDelay: [1000, 2500],
typingDurationPerChar: 50
});
// غیرفعال کردن حالت انسانی (حالت ربات فوق سریع و پاسخ لحظهای)
client.disableHumanize();
// تاخیر دلخواه با تابع کمکی sleep
await client.sleep(1500);
مکانیزم شبیهسازی هوشمند و ضد مسدودی
سیستم آنتیاسپم بله اکانتهایی که بدون تاخیر طبیعی پیام ارسال میکنند را شناسایی میکند. BaleX تمام رفتارهای کاربر فیزیکی را بازتولید میکند:
۱. تاخیر دیدن پیام (Seen Delay)
پس از دریافت پیام، کلاینت بلافاصله تیک دوم را نمیزند، بلکه بعد از یک تاخیر تصادفی انسانی پیام را خوانده شده علامتگذاری میکند.
۲. شبیهسازی فکر کردن و تایپ
طول پیام با ضریب میلیثانیه بر کاراکتر سنجیده شده و سیگنال تایپینگ به مدت متناسب ارسال میشود.
۳. هارتبیت پسزمینه
کلاینت به صورت خودکار هر ۶۰ ثانیه وضعیت آنلاین بودن را تمدید میکند تا ارتباط طبیعی به نظر برسد.
نکات طلایی جلوگیری از مسدودی و بن شدن
- همواره humanize را فعال بگذارید: در اکانتهای شخصی و یوزرباتها، تاخیرهای طبیعی ضامن بقای اکانت هستند.
- از ارسال پیام انبوه به ناشناسها پرهیز کنید: ارسال بیش از ۲۰ پیام در دقیقه به افرادی که شماره شما را ندارند میتواند اکانت را ریپورت کند.
- از سشن پایدار استفاده کنید: لاگینهای مکرر و دریافت پشت سر هم پیامک باعث ایجاد خطای
FLOOD_WAITدر سرور بله میشود.
معماری پروتکل باینری Protobuf و gRPC-Web
بله از فریمهای استاندارد gRPC-Web با پیشوند ۵ بایتی استفاده میکند:
| بایتها | فیلد | توضیحات |
|---|---|---|
0 (1 بایت) |
Flag فریم | مقدار 0x00 برای داده (Data) و 0x80 برای تریلر وضعیت (Trailers) |
1..4 (4 بایت) |
Length طول بسته | طول باینری بسته پروتوباف به صورت Big-Endian 32-bit |
5..end |
Protobuf Payload | بدنه باینری کدگذاری شده مطابق اسکیماهای Protobuf Wire |
فراخوانی عمومی از طریق متد invoke و پراکسیهای داینامیک
تمامی ۵۳ سرویس و ۶۳۶ متد بله به صورت شیءهای داینامیک در کلاینت در دسترس هستند: client.<namespace>.<methodName>(payload). همچنین میتوانید مستقیماً از متد client.invoke() برای ارسال هر RPC دلخواه استفاده نمایید:
// روش ۱: فراخوانی از طریق پراکسی خودکار سرویس
const res1 = await client.users.loadFullUsers({ userIds: [123456789] });
// روش ۲: فراخوانی مستقیم و عمومی با متد invoke
const res2 = await client.invoke('bale.users.v1.Users', 'LoadFullUsers', {
userIds: [123456789]
});
کاتالوگ جامع ۱۰۶ متد کاربردی سطح بالای کلاینت بله (BaleClient)
کلاس BaleClient بیش از ۱۰۶ متد سطح بالا و آماده (Convenience Methods) را برای تسریع برنامهنویسی و عدم درگیری مستقیم با باینری وایر ارائه میدهد. جدول زیر مرجع کامل تمامی این متدها در ۱۴ دستهبندی است:
| دستهبندی | نام متد و پارامترها | نوع بازگشتی | توضیحات و کاربرد |
|---|---|---|---|
| احراز هویت | client.connect() | Promise<void> | برقراری اتصال سوکت با سرورهای پروتکل بله. |
| احراز هویت | client.disconnect() | void | قطع ایمن سوکت و لغو هارتبیتها. |
| احراز هویت | client.sendCode(phoneNumber) | Promise<AuthCodeResponse> | ارسال کد تایید پیامکی ۵ رقمی به شماره همراه. |
| احراز هویت | client.signIn(code, hash) | Promise<AuthResult> | تایید کد ۵ رقمی و ورود به حساب کاربری. |
| احراز هویت | client.signInWithPassword(pass, hash) | Promise<AuthResult> | تایید رمز عبور دو مرحلهای (2FA) بله. |
| احراز هویت | client.logout() | Promise<void> | خروج کامل از حساب و باطلسازی نشست. |
| احراز هویت | client.isConnected | boolean | وضعیت فعال بودن اتصال زنده سوکت. |
| احراز هویت | client.me | User | اطلاعات نمایه کاربر متصل فعلی. |
| پیامرسانی | client.sendMessage(peer, text, opts) | Promise<SentMessage> | ارسال پیام متنی با پشتیبانی از ریپلای و رفتار انسانی. |
| پیامرسانی | client.sendTextMessage(peerId, text, isGroup) | Promise<SentMessage> | ارسال سریع پیام متنی با شناسه عددی چت. |
| پیامرسانی | client.forwardMessages(toPeer, fromPeer, mids, opts) | Promise<void> | فوروارد گروهی پیامها بین گفتگوها. |
| پیامرسانی | client.editMessage(peer, messageId, newText) | Promise<void> | ویرایش پیام ارسالشده در گفتگو. |
| پیامرسانی | client.pinMessage(peer, messageId) | Promise<void> | پین کردن پیام در گفتگوی خصوصی یا گروه. |
| پیامرسانی | client.deleteMessages(peer, mids) | Promise<void> | حذف یک یا چند پیام در گفتگو. |
| پیامرسانی | client.clearChat(peer) | Promise<void> | پاکسازی کامل تاریخچه گفتگو برای دو طرف. |
| پیامرسانی | client.loadDialogs(limit, endDate) | Promise<DialogsResponse> | دریافت لیست گفتگوهای فعال کاربر. |
| پیامرسانی | client.loadHistory(peer, limit, date) | Promise<HistoryResponse> | دریافت تاریخچه پیامهای یک چت مشخص. |
| پیامرسانی | client.markAsReceived(peer, date) | Promise<void> | اعلام تحویل پیام به سرور (تکتیک خاکستری). |
| پیامرسانی | client.markAsRead(peer, date) | Promise<void> | اعلام خوانده شدن پیام (دو تیک آبی). |
| چندرسانهای | client.sendPhoto(peer, photo, opts) | Promise<SentMessage> | ارسال عکس به کاربر، گروه یا کانال. |
| چندرسانهای | client.sendVoice(peer, voice, opts) | Promise<SentMessage> | ارسال ویس با انیمیشن موج صوتی. |
| چندرسانهای | client.sendAudio(peer, audio, opts) | Promise<SentMessage> | ارسال فایل صوتی و آهنگ. |
| چندرسانهای | client.sendVideo(peer, video, opts) | Promise<SentMessage> | ارسال ویدیو همراه با پیشنمایش. |
| چندرسانهای | client.sendDocument(peer, doc, opts) | Promise<SentMessage> | ارسال انواع اسناد و فایلهای دانلودی. |
| چندرسانهای | client.sendSticker(peer, stickerId, hash, packId) | Promise<SentMessage> | ارسال استیکر با شناسه باینری. |
| گروه | client.createGroup(title, userIds) | Promise<GroupInfo> | ساخت گروه جدید همراه با افزودن اعضای اولیه. |
| گروه | client.getGroup(groupId) | Promise<GroupInfo> | دریافت اطلاعات و اعضای یک گروه. |
| گروه | client.inviteMembers(groupId, userIds) | Promise<void> | افزودن اعضای جدید به گروه. |
| گروه | client.kickMember(groupId, userId) | Promise<void> | اخراج یک عضو از گروه. |
| گروه | client.setGroupTitle(groupId, title) | Promise<void> | تغییر نام و عنوان گروه. |
| گروه | client.leaveGroup(groupId) | Promise<void> | ترک گروه توسط کاربر فعلی. |
| مخاطبین | client.getUser(userId) | Promise<UserInfo> | دریافت مشخصات کامل حساب کاربری. |
| مخاطبین | client.getContacts() | Promise<Contact[]> | دریافت لیست تمام مخاطبین همگامشده در بله. |
| مخاطبین | client.importContacts(contacts) | Promise<ImportResult> | همگامسازی گروهی مخاطبین با دفترچه تلفن. |
| مخاطبین | client.addContact(phone, name) | Promise<Contact> | افزودن مخاطب جدید با شماره تلفن. |
| مخاطبین | client.addContactByUid(uid, accessHash) | Promise<Contact> | افزودن مخاطب با شناسه کاربری. |
| مخاطبین | client.removeContact(uid, accessHash) | Promise<void> | حذف مخاطب از دفترچه تلفن. |
| مخاطبین | client.searchContacts(query) | Promise<SearchResult> | جستجوی نام و نامکاربری در مخاطبین. |
| پروفایل | client.editName(name) | Promise<void> | تغییر نام نمایشی اکانت کاربر. |
| پروفایل | client.editAbout(about) | Promise<void> | تغییر بیوگرافی (About) اکانت. |
| پروفایل | client.editUsername(username) | Promise<void> | تغییر یا ثبت نامکاربری عمومی (@username). |
| پروفایل | client.checkUsername(username) | Promise<boolean> | استعلام آزاد بودن یک آیدی در بله. |
| حریم خصوصی | client.blockUser(userId) | Promise<void> | مسدودسازی یک کاربر (بلاک). |
| حریم خصوصی | client.unblockUser(userId) | Promise<void> | رفع مسدودیت کاربر مسدودشده. |
| حریم خصوصی | client.loadBlockedUsers() | Promise<UserInfo[]> | دریافت لیست تمامی کاربران مسدودشده. |
| واکنش | client.setReaction(peer, msgId, emoji) | Promise<void> | ثبت واکنش ایموجی (ریاکشن) روی پیام. |
| واکنش | client.removeReaction(peer, msgId, emoji) | Promise<void> | حذف واکنش ثبتشده از روی پیام. |
| واکنش | client.getReactions(peer, messageIds) | Promise<ReactionInfo[]> | دریافت لیست و آمار واکنشهای ثبتشده. |
| پوشهها | client.loadFolders() | Promise<Folder[]> | دریافت لیست پوشهبندی چتهای کاربر. |
| پوشهها | client.createFolder(title, peerIds) | Promise<Folder> | ایجاد پوشه جدید برای دستهبندی گفتگوها. |
| پوشهها | client.deleteFolder(folderId) | Promise<void> | حذف یک پوشه از گفتگوها. |
| نظرسنجی | client.sendPoll(peer, question, opts, cfg) | Promise<SentMessage> | ارسال نظرسنجی استاندارد در گروه یا کانال. |
| نظرسنجی | client.createPoll(question, opts, cfg) | Promise<PollInfo> | ایجاد آبجکت نظرسنجی با تنظیمات چندگزینهای یا کوییز. |
| نظرسنجی | client.getPollResults(pollId) | Promise<PollResults> | دریافت آرای ثبتشده و درصد گزینهها. |
| نظرسنجی | client.closePoll(pollId) | Promise<void> | بستن و پایان مهلت شرکت در نظرسنجی. |
| پاکت نقدی | client.sendGiftPacket(options) | Promise<GiftPacketResult> | ارسال پاکت هدیه ریالی با تقسیم مساوی یا رندوم. |
| پاکت نقدی | client.openGiftPacket(options) | Promise<OpenGiftResult> | باز کردن و مشاهده محتوای پاکت هدیه نقدی. |
| پاکت نقدی | client.claimGiftPacket(options) | Promise<ClaimResult> | برداشت و واریز مبلغ هدیه به کیفپول بله. |
| پاکت نقدی | client.getGiftPacketReceivers(options) | Promise<Receiver[]> | مشاهده لیست دریافتکنندگان و مبالغ واریزشده. |
| پاکت نقدی | client.getGiftPacketPaymentToken(options) | Promise<string> | دریافت توکن پرداخت جهت شارژ پاکت نقدی. |
| پاکت طلا | client.sendGoldGiftPacket(options) | Promise<GoldPacketResult> | ارسال پاکت هدیه طلا بر حسب میلیگرم طلا. |
| پاکت طلا | client.openGoldGiftPacket(packetId) | Promise<GoldOpenResult> | باز کردن پاکت طلای ارسالی در گفتگو. |
| پاکت طلا | client.claimGoldGiftPacket(packetId) | Promise<GoldClaimResult> | دریافت طلا و ثبت در گاوصندوق طلای بله. |
| پاکت طلا | client.getGoldGiftPacketWinners(packetId) | Promise<GoldWinner[]> | لیست برندگان و مقادیر طلای برداشتهشده. |
| مینیاپ | client.createMiniAppParams(botUserId, opts) | MiniAppParams | تولید بسته پارامترهای استاندارد initData با امضای HMAC-SHA256. |
| مینیاپ | client.createInitData(options) | string | تولید رشته خام دادههای اولیه کلاینت. |
| مینیاپ | client.signInitData(data, botToken) | string | امضای دیجیتال رشته initData با کلید مخفی بات. |
| مینیاپ | client.validateInitData(initData, token, maxAge) | ValidationResult | اعتبارسنجی سمت سرور صحت هش و تاریخ انقضا. |
| مینیاپ | client.parseInitData(initData) | ParsedInitData | پارس کردن رشته احراز هویت به شیء جاوااسکریپت. |
| مینیاپ | client.buildMiniAppUrl(options) | string | تولید URL کامل اجرای مینیاپ با پارامترها و تم. |
| مینیاپ | client.getMiniAppUrl(options) | Promise<string> | استعلام آدرس نهایی مینیاپ از سرورهای بله. |
| مینیاپ | client.getWebappHash(botUserId, data) | Promise<string> | تولید هش امنیتی نشست وباپ بله. |
| مینیاپ | client.sendMiniAppData(options) | Promise<void> | ارسال داده از مینیاپ به ربات میزبان. |
| مینیاپ | client.getBotMenuButton(botUserId) | Promise<MenuButton> | استعلام وضعیت و لینک دکمه منوی بازو. |
| مینیاپ | client.invokeMiniAppCustomMethod(options) | Promise<any> | فراخوانی متدهای اختصاصی سرور مینیاپ بله. |
| بانکداری | client.inquireDestinationPan(options) | Promise<CardInquiryResult> | استعلام نام دارنده کارت و نام بانک مقصد شتاب. |
| بانکداری | client.transferMoneyByCard(options) | Promise<TransferResult> | انتقال وجه کارت به کارت شتابی با رمز پویا. |
| بانکداری | client.getCardBalance(options) | Promise<CardBalanceResult> | دریافت موجودی واقعی و قابل برداشت کارت بانکی. |
| استوری | client.sendStory(options) | Promise<StoryResult> | انتشار استوری تصویری یا ویدیویی در بله. |
| استوری | client.deleteStory(storyId) | Promise<void> | حذف استوری منتشر شده پیش از موعد. |
| استوری | client.getUserStories(userId) | Promise<Story[]> | مشاهده استوریهای فعال یک کاربر. |
| استوری | client.getStoryViewers(storyId) | Promise<Viewer[]> | مشاهده آمار و لیست بازدیدکنندگان استوری. |
| استوری | client.likeStory(storyId, reaction) | Promise<void> | ثبت لایک یا ریاکشن روی استوری دیگران. |
| زمانبندی | client.scheduleMessage(options) | Promise<ScheduleTask> | زمانبندی پیام برای ارسال خودکار در ساعت مشخص. |
| زمانبندی | client.loadScheduledMessages(peer) | Promise<ScheduleTask[]> | مشاهده پیامهای زمانبندیشده آینده در چت. |
| زمانبندی | client.deleteScheduledMessage(peer, taskId) | Promise<void> | لغو ارسال پیام زمانبندی شده. |
| هوش مصنوعی | client.summarizeLink(link) | Promise<string> | خلاصهسازی خودکار محتوای لینک با مدل زبانی بله. |
| هوش مصنوعی | client.askAI(prompt) | Promise<string> | پرسش مستقیم از هوش مصنوعی یکپارچه بله. |
| حضور و استیلث | client.setOnline(isOnline, timeout) | Promise<void> | تنظیم وضعیت آنلاین/آفلاین در کلاینت بله. |
| حضور و استیلث | client.sendTyping(peer, durationMs, type) | Promise<void> | شبیهسازی وضعیت typing، voice، video برای مخاطب. |
| حضور و استیلث | client.stopTyping(peer, type) | Promise<void> | پایان شبیهسازی تایپینگ. |
| حضور و استیلث | client.setHumanize(value) | void | فعال یا غیرفعال کردن موتور رفتار انسانی. |
| حضور و استیلث | client.enableHumanize(config) | void | پیکربندی تاخیر رندوم تایپینگ، سین و خواندن. |
| حضور و استیلث | client.disableHumanize() | void | غیرفعالسازی تاخیرها برای ارسال فوری (بات مود). |
| حضور و استیلث | client.isHumanized | boolean | وضعیت فعال بودن تنظیمات رفتار انسانی. |
| عمومی | client.sleep(ms) | Promise<void> | تاخیر زمانی در صف درخواستها بدون اشغال CPU. |
| پروتکل باینری | client.invoke(service, method, payload, meta) | Promise<any> | فراخوانی مستقیم و سطح وایر هر متد از ۶۳۶ متد بله. |
کاتالوگ کامل ۵۳ سرویس بله در ۱۰ حوزه کاربردی
تفکیک جامع تمامی ۵۳ سرویس رسمی استخراج شده از پروتکل کلاینت وب بله همراه با تعداد متدها و شرح کاربرد:
۱. احراز هویت، امنیت و تنظیمات (۴ سرویس، ۳۸ متد)
| نام کامل سرویس | پراکسی (Namespace) | متدها | توضیحات |
|---|---|---|---|
bale.auth.v1.Auth | client.auth | 27 | ورود، تایید کد، رمز دومرحلهای، خروج، مدیریت نشستها و لغو نشستهای موازی |
bale.ramz.v1.Ramz | client.ramz | 7 | سیستم تولید، دریافت و اعتبارسنجی رمز دوم یکبار مصرف و پویا (OTP) شتاب |
bale.v1.Configs | client.configs | 3 | دریافت پیکربندی عمومی سرورها، نسخههای فعال و پارامترهای پروتکل |
bale.llm_auth.v1.LLMAuthService | client.lLMAuth | 1 | احراز هویت و دریافت کلید دسترسی به مدلهای زبانی هوش مصنوعی بله |
۲. پیامرسانی، استریم و محتوا (۶ سرویس، ۵۶ متد)
| نام کامل سرویس | پراکسی (Namespace) | متدها | توضیحات |
|---|---|---|---|
bale.messaging.v2.Messaging | client.messaging | 43 | ارسال، ویرایش، حذف، فوروارد، پین، پوشهها و بارگذاری تاریخچه چتها |
bale.schedule.v1.Scheduler | client.scheduler | 6 | زمانبندی ارسال پیام در آینده، لغو یا ویرایش زمان ارسال خودکار |
bale.tldr.v1.TLDR | client.tLDR | 2 | خلاصهسازی خودکار گفتگوها و پیامهای طولانی کانالها با هوش مصنوعی |
bale.turing.v1.AI | client.aI | 2 | ارسال پرامپت و دریافت پاسخ بلادرنگ از موتورهای زبانی هوش مصنوعی تورینگ |
bale.message_stream.v1.MessageStream | client.messageStream | 2 | استریم بلادرنگ پیامها و فیدهای خبری |
bale.maviz.v1.MavizStream | client.mavizStream | 4 | استریم بستههای باینری سوکت ماویز و هماهنگسازی دادهها |
۳. کاربران، مخاطبین و حضور آنلاین (۵ سرویس، ۵۲ متد)
| نام کامل سرویس | پراکسی (Namespace) | متدها | توضیحات |
|---|---|---|---|
bale.users.v1.Users | client.users | 36 | پروفایل کامل، نام، بیو، نام کاربری، دفترچه مخاطبین و مدیریت لیست سیاه |
bale.presence.v1.Presence | client.presence | 11 | وضعیت آنلاین بودن، زمان آخرین بازدید، ارسال وضعیت تایپینگ و اشتراک وضعیت |
bale.anonymous_contact.v1.AnonymousContact | client.anonymousContact | 1 | برقراری تماس امن صوتی بدون آشکارسازی شماره تلفن همراه |
bale.organizations.v1.Organizations | client.organizations | 2 | پروفایل شرکتی، تایید هویت سازمانی و نشانهای تایید |
bale.top_peer.v1.TopPeer | client.topPeer | 2 | محاسبه و دریافت لیست مخاطبین و چتهای پرتکرار کاربر |
۴. گروهها، کانالها و کاوش (۵ سرویس، ۶۸ متد)
| نام کامل سرویس | پراکسی (Namespace) | متدها | توضیحات |
|---|---|---|---|
bale.groups.v1.Groups | client.groups | 50 | ایجاد گروه، لینک دعوت، تغییر ادمین، اخراج و تنظیم دسترسیهای اعضا |
bale.charnet.v1.CharnetService | client.charnet | 11 | جستجو، معرفی کانالها، لیست چهارسو و دستهبندی موضوعی |
bale.recommender.v1.Recommender | client.recommender | 4 | موتور پیشنهاد هوشمند کانالها، چتها و محتوای مرتبط |
bale.falake.v1.Falake | client.falake | 1 | بخش کاوش و فید محتواهای پرطرفدار و ترند فلکه |
bale.fanoos.v1.fanoos | client.fanoos | 2 | سیستم کاوش و پیشنهاد هوشمند فانوس |
۵. خدمات بانکی شتابی و ساب (۴ سرویس، ۳۷ متد)
| نام کامل سرویس | پراکسی (Namespace) | متدها | توضیحات |
|---|---|---|---|
bale.bank.v1.Bank | client.bank | 17 | استعلام کارت مقصد، انتقال کارت به کارت، موجودی و گردش حساب شتاب |
bale.sap.v1.Sap | client.sap | 16 | سامانه پرداخت، قبض، استعلام تراکنشهای شاپرک و خدمات ساب |
bale.microbanki.v1.MicroBanki | client.microBanki | 3 | تسهیلات و خدمات خرد بانکی و استعلام تسهیلات |
bale.my_bank.v1.MyBank | client.myBank | 1 | شعب، اطلاعات و حسابهای متمرکز بانک ملی |
۶. کیفپول، طلا و امور مالی (۷ سرویس، ۶۵ متد)
| نام کامل سرویس | پراکسی (Namespace) | متدها | توضیحات |
|---|---|---|---|
bale.kifpool.v1.Kifpool | client.kifpool | 30 | کیف پولهای ریالی، گردش موجودی، امتیازات بله و باشگاه مشتریان |
bale.wallet.v1.Wallet | client.wallet | 13 | شارژ کیف پول، تسویه و برداشت وجه به حساب بانکی |
bale.pfm.v1.Pfm | client.pfm | 15 | مدیریت مالی شخصی، دستهبندی هزینهها و نمودار دخل و خرج |
bale.giftpacket.v1.GiftPacket | client.giftPacket | 3 | ارسال پاکت هدیه ریالی به شکل مساوی یا شانسی در گروهها |
bale.balebank.v1.GoldGiftPacket | client.goldGiftPacket | 3 | ارسال، دریافت و بازگشایی پاکت هدیه شمش طلا |
bale.balebank.v1.GoldWallet | client.goldWallet | 1 | موجودی و گردش حساب طلایی بلهبانک |
bale.crowdfunding.v1.CrowdFunding | client.crowdFunding | 2 | پویشهای جمعسپاری مالی، نیکوکاری و خیریه |
۷. رباتها، خدمات و ابزارکها (۵ سرویس، ۳۱ متد)
| نام کامل سرویس | پراکسی (Namespace) | متدها | توضیحات |
|---|---|---|---|
bale.ketf.v1.Ketf | client.ketf | 14 | پلتفرم رباتها، کلیک دکمههای اینلاین، دستورات و هوکها |
bale.garson.v1.Garson | client.garson | 11 | سامانه سفارش خدمات و غذا، مدیریت میز و پرداخت گارسون |
bale.appzar.v1.Appzar | client.appzar | 3 | ابزارکها و مینیاپلیکیشنهای درونبرنامهای |
bale.timche.v1.Timche | client.timche | 5 | سامانه فروشگاهی تیمچه و خدمات تجاری |
bale.ghasedak.v1.GhasedakService | client.ghasedak | 2 | ارسال نوتیفیکیشن و پیامکهای سامانه قاصدک |
۸. رسانه، استوری، جلسات و صوت (۶ سرویس، ۷۹ متد)
| نام کامل سرویس | پراکسی (Namespace) | متدها | توضیحات |
|---|---|---|---|
bale.story.v1.Story | client.story | 24 | ارسال، مشاهده، استوری ۲۴ ساعته و آمار بازدیدکنندگان |
bale.meet.v1.Meet | client.meet | 30 | جلسات صوتی و تصویری آنلاین، اشتراک تصویر و کنترل میکروفن |
bale.v1.Images | client.images | 10 | مدیریت تصاویر، برش عکس و سایزهای آواتار پروفایل |
ai.bale.server.Files | client.files | 7 | دریافت لینک مستقیم آپلود و دانلود فایلها از سرور نسیم |
bale.shared_media.v1.SharedMediaService | client.sharedMedia | 2 | دریافت تاریخچه تمام عکسها، فایلها و لینکهای ردوبدل شده |
bale.pishvaz.v1.Pishvaz | client.pishvaz | 3 | آوای پیشواز تماس و پخش نمونههای صوتی |
۹. واکنشها، نظرسنجی و پشتیبانی (۵ سرویس، ۱۹ متد)
| نام کامل سرویس | پراکسی (Namespace) | متدها | توضیحات |
|---|---|---|---|
bale.abacus.v1.Abacus | client.abacus | 9 | ثبت، دریافت و مدیریت ریاکشنهای ایموجی روی پیامها |
bale.poll.v1.Poll | client.poll | 5 | ساخت نظرسنجی، کوییزهای چندگزینهای و بستن نظرسنجی |
bale.feedback.v1.FeedBack | client.feedBack | 1 | ارسال فیدبک، نظرات و پیشنهادها به تیم توسعه بله |
bale.report.v1.Report | client.report | 2 | گزارش اسپم، کلاهبرداری یا تخلف محتوا |
bale.negah.v1.Negah | client.negah | 1 | سرویس نظارت و ثبت رویدادهای نگاه |
۱۰. تبلیغات، فروشگاه و خدمات ویژه (۵ سرویس، ۱۷۴ متد)
| نام کامل سرویس | پراکسی (Namespace) | متدها | توضیحات |
|---|---|---|---|
bale.advertisement.v1.Advertisement | client.advertisement | 126 | سیستم تبلیغات بله، رزرو جایگاه، بودجه و کمپینها |
bale.market.v1.Market | client.market | 26 | فروشگاه کالا، ثبت سفارش و رهگیری سبد خرید |
bale.search.v1.Search | client.search | 12 | موتور جستجوی سراسری پیامها، کاربران، کانالها و فایلها |
bale.premium.v1.Premium | client.premium | 7 | اشتراک پریمیوم، استیکرهای انحصاری و افزایش محدودیتها |
bale.magazine.v1.Magazine | client.magazine | 9 | پایگاه اخبار و مقالات مجله بله |
جستجوگر تعاملی تمامی ۶۳۶ متد رسمی بله (Live Method Explorer)
میتوانید در کادر زیر هر یک از ۶۳۶ متد رسمی بله را جستجو کرده یا بر اساس دستهبندی فیلتر نمایید تا کد فراخوانی آن آماده کپی شود:
جدول کدهای خطای سرور بله و راهکارها
| کد خطای gRPC / متنی | علت بروز | اقدام و راهکار در BaleX |
|---|---|---|
PHONE_CODE_INVALID |
کد پیامک اشتباه یا نامعتبر وارد شده است. | تابع signIn ارقام فارسی را قبل از ارسال تصحیح میکند؛ کد ۵ رقمی را مجدد بررسی کنید. |
PHONE_CODE_EXPIRED |
کد پیامک به دلیل گذشت زمان منقضی شده است. | دوباره متد sendCode را فراخوانی کنید. |
PHONE_PASSWORD_INVALID |
رمز عبور دومرحلهای (۲FA) صحیح نیست. | رمز عبور صحیح حساب را در signInWithPassword وارد کنید. |
FLOOD_WAIT |
تعداد درخواستهای مکرر فراتر از حد مجاز بوده است. | موتور humanize به طور خودکار تا پایان زمان اعلامشده مکث میکند. |
INVALID_PAN |
شماره کارت شتابی وارد شده معتبر نیست. | شماره کارت ۱۶ رقمی را با الگوریتم Luhn بررسی کنید. |
4401 onUnauthenticated |
اتصال وبسوکت بدون توکن معتبر سشن انجام شده است. | ابتدا لاگین را کامل کنید و سپس با توکن معتبر متصل شوید. |
سوالات متداول (FAQ)
آیا استفاده از این کتابخانه نیاز به دسترسی روت یا گوشی روشن دارد؟
خیر، کتابخانه BaleX کامپوننتی مستقل و سمت سرور است و بر روی هر سرور لینوکس، مک، ویندوز و کانتینرهای داکر بدون نیاز به گوشی روشن، شبیهساز یا مرورگر کار میکند.
چگونه میتوان روی سرور لینوکس هاست کرد؟
کافیست با دستور npm install github:Zellias/balex کتابخانه را نصب کرده و آن را با pm2 یا به صورت سرویس systemd اجرا نگه دارید.
آیا با تغییر آیپی سشن باطل میشود؟
خیر، سشن بله متصل به توکن JWT است و تا زمانی که خروج از حساب نزده باشید یا از طریق اپلیکیشن سشن را لغو نکرده باشید، برای ماهها پایدار میماند.
اتصال و اجرا از طریق زبان Go (Golang)
اگر پروژه یا سرور اصلی شما به زبان Go (Golang) نوشته شده است، میتوانید از قابلیت پل ارتباطی پرسرعت (IPC / HTTP Bridge) کتابخانه برای ارسال دستورات و دریافت رویدادها استفاده کنید.
۲. پل سرور HTTP / JSON-RPC: برقراری ارتباط از طریق ارسال درخواستهای استاندارد HTTP REST به صورت میکروسرویس مستقل.
روش اول: اجرای مستقیم از Go با Subprocess (STDIO)
کد کامل زبان Go برای اجرای پروسس و ارسال دستورات بدون نیاز به وبسرور:
package main
import (
"bufio"
"encoding/json"
"fmt"
"os/exec"
)
type Request struct {
ID int `json:"id"`
Action string `json:"action"`
Method string `json:"method,omitempty"`
Token string `json:"token,omitempty"`
Params interface{} `json:"params,omitempty"`
}
type Response struct {
ID int `json:"id"`
Success bool `json:"success"`
Result json.RawMessage `json:"result"`
Error string `json:"error,omitempty"`
}
func main() {
// اجرای پل ارتباطی به عنوان Child Process
cmd := exec.Command("node", "src/bridge.js", "--stdio")
stdin, _ := cmd.StdinPipe()
stdout, _ := cmd.StdoutPipe()
_ = cmd.Start()
reader := bufio.NewReader(stdout)
// خواندن پیام اولیه آمادهباش
initLine, _ := reader.ReadBytes('
')
fmt.Println("Bridge ready:", string(initLine))
// ارسال دستور به کتابخانه
req, _ := json.Marshal(Request{
ID: 1,
Action: "call",
Method: "sendMessage",
Params: []interface{}{123456789, "سلام از Go!"},
})
stdin.Write(append(req, '
'))
// دریافت پاسخ
resLine, _ := reader.ReadBytes('
')
var resp Response
json.Unmarshal(resLine, &resp)
fmt.Printf("نتیجه اجرای متد در Go: %+v
", resp)
}
روش دوم: اجرای دائم به عنوان پل HTTP
ابتدا پل را در پسزمینه با دستور زیر اجرا کنید:
# اجرای سرور پل ارتباطی روی پورت ۸۷۶۵
npx balex bridge --port 8765
سپس در هر پروژه Go با پکیج استاندارد net/http به آن متصل شوید:
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
payload, _ := json.Marshal(map[string]interface{}{
"method": "sendMessage",
"params": []interface{}{
123456789, // شناسه کاربر یا گروه
"پیام خودکار ارسال شده از سرور Go",
},
})
resp, err := http.Post("http://127.0.0.1:8765/api/call", "application/json", bytes.NewBuffer(payload))
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("وضعیت ارسال HTTP:", resp.Status)
}