کتابخانه پروتکل رسمی BaleX

کتابخانه BaleX یک پیاده‌سازی مستقل، سبک، مدرن و فوق‌العاده سریع از پروتکل ارتباطی پیام‌رسان بله (Bale Messenger) سمت سرور بر پایه باینری (Protobuf / gRPC-Web / WebSocket) و بات رسمی بله (docs.bale.ai) است که در محیط Node.js / TypeScript پیاده‌سازی شده و از اتصال و اجرای مستقیم از طریق زبان Go (Golang) به طور کامل پشتیبانی می‌کند.

ارتباط مستقیم باینری و بدون واسطه
این کتابخانه برخلاف ابزارهایی چون Puppeteer یا سلنیوم، بدون باز کردن مرورگر و با ارسال مستقیم بسته‌های رمزنگاری‌شده باینری پروتکل بله با سرورهای maviz-ws.bale.ai تبادل داده می‌کند که موجب مصرف ناچیز رم (کمتر از ۲۰ مگابایت)، سرعت میلی‌ثانیه‌ای و امنیت بالا می‌شود.

ویژگی‌های برجسته BaleX

⚡

ارتباط باینری Protobuf خالص

انکود و دیکود کاملاً بومی و خالص پکت‌های پروتکل بله بدون هیچ وابستگی سنگین خارجی.

💳

عملیات بانکی شتابی

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

🕵️‍♂️

موتور هوشمند ضد مسدودی

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

🌐

۵۳ سرویس و ۶۳۶ متد

پوشش صد درصدی تمام قابلیت‌های استخراج‌شده از پروتکل رسمی بله همراه با پراکسی‌های خودکار.

روش ۱: نصب مستقیم از گیت‌هاب (GitHub)

شما می‌توانید این کتابخانه را مستقیماً از مخزن گیت‌هاب بر روی پروژه خود نصب نمایید:

Terminal
# نصب با نام کاربری و مخزن گیت‌هاب
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

Terminal
npm install balex

شروع سریع (Quickstart)

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

JavaScript (Node.js)
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 برقرار می‌کند و دریافت زنده رویدادها را آغاز می‌نماید:

JavaScript
// اتصال و ثبت هارت‌بیت حضور آنلاین
await client.connect();
console.log('وضعیت اتصال:', client.isConnected); // true

قطع اتصال سوکت (disconnect)

متد client.disconnect() ارتباط زنده را به شکل استاندارد خاتمه داده، تایمرهای هارت‌بیت را متوقف و منابع حافظه را آزاد می‌کند:

JavaScript
client.disconnect();
console.log('اتصال قطع شد. وضعیت:', client.isConnected); // false

احراز هویت و ورود به حساب (Authentication)

فرآیند لاگین در پیام‌رسان بله در دو الی سه مرحله به صورت درخواست‌های gRPC-Web Unary روی سرور رسمی https://maviz-ws.bale.ai انجام می‌شود.

مرحله ۱: درخواست ارسال پیامک (sendCode)

متد client.sendCode(phoneNumber) کد تایید ورود را به شماره همراه کاربر ارسال می‌کند و شناسه تراکنش امنیتی transactionHash را بازمی‌گرداند:

JavaScript
// شماره همراه با صفر، بدون صفر یا پیشوند بین‌المللی پذیرفته می‌شود
const res = await client.sendCode('09372570490');
console.log('کد پیامک شد. شناسه تراکنش:', res.transactionHash);

مرحله ۲: اعتبارسنجی کد ۵ رقمی (signIn)

متد client.signIn(code, transactionHash) کد ۵ رقمی دریافتی از پیامک را ارسال نموده و در صورت صحت، سشن را ایجاد و کلاینت را متصل می‌کند. ارقام فارسی (مانند ۱۵۰۱۱) به طور خودکار به ارقام انگلیسی تبدیل می‌گردند:

JavaScript
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) احراز هویت را کامل کنید:

JavaScript
const session = await client.signInWithPassword('رمز_دومرحله‌ای_حساب');
console.log('لاگین دو مرحله‌ای تکمیل شد. خوش آمدید:', session.user.name);

ذخیره و بازیابی نشست (Session Persistence)

نیازی به ورود مجدد و دریافت پیامک در هر بار اجرای برنامه نیست؛ BaleX از دو کلاس StringSession و FileSession پشتیبانی می‌کند:

JavaScript
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) را به سرورهای بله ارسال نموده، توکن محلی را پاکسازی و سوکت را می‌بندد:

JavaScript
await client.logout();
console.log('با موفقیت از حساب کاربری خارج شدید.');

پیام‌رسانی و گفتگوها (Messaging)

ارسال پیام متنی با پشتیبانی کامل از ریپلای، کوت (نقل‌قول) و شبیه‌سازی هوشمند تاخیر انسانی:

ارسال پیام پیشرفته (sendMessage)

JavaScript
// ۱. ارسال پیام ساده به کاربر یا گروه
await client.sendMessage(123456789, 'سلام! پیام ارسال‌شده از طریق BaleX 🚀');

// ۲. ارسال با ریپلای به پیام دیگر و تعیین مدت شبیه‌سازی تایپ
await client.sendMessage(123456789, 'پاسخ به سوال شما...', {
  replyToMessageId: 987654321012n,
  simulateTyping: true,
  typingDuration: 2500 // ۲.۵ ثانیه نمایش در حال تایپ
});

ارسال پیام متنی سریع (sendTextMessage)

JavaScript
// ارسال پیام به چت خصوصی (کاربر)
await client.sendTextMessage(123456789, 'سلام کاربر گرامی');

// ارسال پیام به گروه با مشخص کردن آرگومان isGroup = true
await client.sendTextMessage(987654321, 'اطلاعیه جدید گروه', true);

تایید تحویل و خوانده‌شدن پیام‌ها (Read Receipts)

ارسال سیگنال دریافت (یک تیک خاکستری) و خوانده شدن (دو تیک آبی):

JavaScript
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) دسته‌بندی شرح و کاربرد در بله
message55پیام‌رسانیدریافت پیام جدید (متنی، چندرسانه‌ای، پاکت هدیه، سرویس) با متدهای هوشمند
messageEdit162پیام‌رسانیویرایش متن، کپشن یا محتوای پیام ارسال‌شده
messageDelete46پیام‌رسانیحذف یک یا چند پیام در گفتگو توسط کاربر یا مدیر
chatClear47پیام‌رسانیپاکسازی کامل تاریخچه گفتگو برای دو طرف
chatDelete48پیام‌رسانیحذف کل گفتگو از لیست چت‌ها
messageReceived54پیام‌رسانیتایید رسیدن پیام به دستگاه مقصد (تک‌تیک خاکستری)
messageRead19پیام‌رسانیتایید خوانده شدن پیام توسط مخاطب (دو تیک آبی)
messageReadByMe50پیام‌رسانیعلامت‌گذاری پیام به عنوان خوانده‌شده توسط اکانت خودمان
chatShow93پیام‌رسانیخروج گفتگو از حالت مخفی و نمایش مجدد در لیست چت‌ها
chatArchive94پیام‌رسانیآرشیو شدن گفتگو یا پوشه
chatFavourite95پیام‌رسانیافزودن گفتگو به برگزیده‌ها (Favorite)
messageDateChanged163پیام‌رسانیتغییر برچسب زمانی پیام
stickerCollectionsChanged164پیام‌رسانیبه‌روزرسانی کالکشن‌ها و پکیج‌های استیکر کاربر
messageQuotedChanged169پیام‌رسانیتغییر یا حذف پیام مرجع ریپلای شده
mentionReadByMe52829پیام‌رسانیسین شدن پیام‌های حاوی منشن کاربر
pinnedDialogsChanged52830پیام‌رسانیتغییر در لیست یا ترتیب گفتگوهای پین‌شده
dialogsMarkedAsRead54335پیام‌رسانیعلامت‌گذاری گروهی گفتگوها به عنوان خوانده‌شده
dialogsMarkedAsUnread54336پیام‌رسانیعلامت‌گذاری گروهی چت‌ها به عنوان خوانده‌نشده
dialogsUnpinned54339پیام‌رسانیبرداشته شدن سنجاق و پین گفتگو
messagePinned54340پیام‌رسانیپین و سنجاق شدن پیام جدید در گروه یا کانال
messagesUnPinned54341پیام‌رسانیبرداشته شدن سنجاق یک یا چند پیام
dialogArchiveStatus54345پیام‌رسانیتغییر وضعیت فعال/غیرفعال آرشیو گفتگو
messageStreamChunks54351پیام‌رسانیدریافت بسته‌های زنده متن تولیدی هوش مصنوعی یا استریم (Streaming)
reaction222 / 52825واکنش‌هاثبت، تغییر یا حذف واکنش ایموجی روی پیام توسط کاربران
messageNewReaction54323واکنش‌هاثبت واکنش جدید با جزئیات کامل کاربر و ایموجی
messageReactionsReadByMe52832واکنش‌هاسین شدن واکنش‌های ثبت‌شده توسط کاربر
typing6حضور و وضعیتشروع تایپ، ضبط صدا، ارسال ویدیو یا آپلود فایل توسط مخاطب
typingStop81حضور و وضعیتتوقف وضعیت در حال نوشتن مخاطب
userOnline7حضور و وضعیتآنلاین شدن کاربر در پلتفرم بله
userOffline8حضور و وضعیتآفلاین شدن کاربر همراه با برچسب زمانی آخرین بازدید
userLastSeen9حضور و وضعیتتغییر در تنظیمات حریم خصوصی یا وضعیت آخرین بازدید کاربر
presenceAliasحضور و وضعیتشنونده سراسری هرگونه تغییر وضعیت آنلاین/آفلاین/بازدید
userAvatarChanged16کاربر و نمایهتغییر یا حذف عکس پروفایل کاربر
userNameChanged32کاربر و نمایهتغییر نام و نام‌خانوادگی نمایشی کاربر
userLocalNameChanged51کاربر و نمایهتغییر نام ذخیره شده مخاطب در دفترچه تلفن
userContactsChanged134کاربر و نمایهبه‌روزرسانی لیست مخاطبین همگام‌شده
userNickChanged209کاربر و نمایهتغییر یا ثبت نام‌کاربری عمومی (Username)
userAboutChanged210کاربر و نمایهتغییر بیوگرافی (About / Bio) نمایه کاربر
userPreferredLanguagesChanged212کاربر و نمایهتغییر زبان مورد نظر کاربر در تنظیمات بله
userTimeZoneChanged216کاربر و نمایهتغییر منطقه زمانی حساب کاربری
userBotCommandsChanged217کاربر و نمایهتغییر در لیست دستورات ثبت‌شده برای ربات
userBlocked2629کاربر و نمایهمسدودسازی یک کاربر (بلاک)
userUnblocked2630کاربر و نمایهرفع مسدودیت کاربر (آنبلاک)
phoneNumberChanged52803کاربر و نمایهتغییر شماره تلفن همراه متصل به حساب کاربری
contactsAdded40کاربر و نمایهافزوده شدن مخاطب جدید به دفترچه تلفن
contactsRemoved41کاربر و نمایهحذف مخاطب از دفترچه تلفن بله
allContactsRemoved54353کاربر و نمایهپاکسازی کامل تمام مخاطبین حساب
groupOnline33گروه و کانالتغییر تعداد اعضای آنلاین گروه
groupNicknameChanged57گروه و کانالتغییر آیدی یا لینک عمومی گروه
groupMessagePinned721گروه و کانالپین شدن پیام جدید در گروه
groupPinRemoved722گروه و کانالبرداشته شدن سنجاق پیام گروه
groupRestrictionChanged723گروه و کانالتغییر در محدودیت‌های اعمال‌شده روی گروه
groupTitleChanged2609گروه و کانالتغییر عنوان و نام گروه
groupAvatarChanged2610گروه و کانالتغییر عکس نمایه و آواتار گروه
groupMemberChanged2612گروه و کانالتغییر وضعیت یا نقش عضو در گروه
groupExtChanged2613گروه و کانالتغییر اکستنشن‌ها و ویژگی‌های تکمیلی گروه
groupMembersUpdated2614گروه و کانالبه‌روزرسانی جامع لیست اعضای گروه
groupTopicChanged2616گروه و کانالتغییر موضوع یا دسته‌بندی موضوعی گروه
groupAboutChanged2617گروه و کانالتغییر توضیحات و بیوگرافی گروه
groupOwnerChanged2619گروه و کانالانتقال مالکیت اصلی گروه به کاربر دیگر
groupHistoryShared2620گروه و کانالتغییر وضعیت دسترسی اعضای جدید به تاریخچه چت
groupMembersCountChanged2622گروه و کانالتغییر تعداد کل اعضای گروه
groupMemberDiff2623گروه و کانالرویداد پیوستن یا خروج عضو به گروه
groupCanSendMessagesChanged2624گروه و کانالتغییر مجوز ارسال پیام اعضا (بستن یا باز کردن چت)
groupCanViewMembersChanged2625گروه و کانالتغییر مجوز دیدن لیست اعضا توسط کاربران عادی
groupCanInviteMembersChanged2626گروه و کانالتغییر دسترسی اعضا جهت دعوت دیگران
groupMemberAdminChanged2627گروه و کانالارتقا به مدیر یا تنزل مقام در گروه
groupBecameOrphaned2628گروه و کانالبدون مالک و مدیر شدن گروه
groupMemberPermissionsChanged52804گروه و کانالتغییر ریزمجوزهای یک عضو خاص در گروه
groupDefaultPermissionsChanged52805گروه و کانالتغییر مجوزهای پیش‌فرض عمومی گروه
channelNickChanged2880گروه و کانالتغییر نام‌کاربری یا شناسه عمومی کانال
channelAdvertisementTypeChanged52801گروه و کانالتغییر نوع تبلیغات فعال درون کانال
channelAdTagIdChanged52802گروه و کانالتغییر شناسه تگ‌های تبلیغاتی کانال
channelSignMessagesChanged54354گروه و کانالفعال یا غیرفعال شدن امضای نام نویسنده در کانال
slowModeChanged54355گروه و کانالتنظیم حالت آرام (Slow Mode) و تاخیر ارسال پیام اعضا
callStarted52807تماس‌هاشروع تماس صوتی یا تصویری
callAccepted52808تماس‌هاپذیرش و برقراری تماس توسط مخاطب
callDiscarded52809تماس‌هاقطع شدن، رد یا پایان یافتن تماس
callReceived52810تماس‌هادریافت زنگ تماس ورودی
groupCallStarted52811تماس‌هاشروع تماس گروهی درون گروه یا کانال
groupCallEnded52812تماس‌هاپایان تماس صوتی یا تصویری گروهی
callReactionSent52813تماس‌هاارسال واکنش ایموجی حین مکالمه زنده
callUpgraded52816تماس‌هاارتقای تماس دو نفره به تماس گروهی
peersInvited52817تماس‌هادعوت کاربران جدید به تماس در حال اجرا
multiPeerCallStarted52818تماس‌هاآغاز کنفرانس و تماس چندطرفه
peersStateChanged52819تماس‌هاتغییر وضعیت اعضا در تماس (میکروفون، دوربین، ...)
callAliasتماس‌هاشنونده جامع و یکپارچه تمامی رویدادهای تماس
giftPacketCustomپاکت هدیهدریافت پیام پاکت هدیه نقدی ریالی در گفتگو
goldGiftPacketCustomپاکت هدیهدریافت پیام پاکت هدیه طلای بله در گفتگو
giftPacketOpenedService 17/18پاکت هدیهرویداد باز شدن پاکت هدیه توسط یکی از کاربران و دریافت مبلغ
miniAppDataService 21مینی‌اپدریافت داده‌های ارسال‌شده از مینی‌اپ/وب‌اپ به ربات
serviceMessageTag 11پیام سرویسپیام‌های سیستمی بله (عضویت، اخراج، تغییر عنوان، ...)
groupCreatedService 1پیام سرویسرویداد ساخته شدن گروه جدید
userInvitedService 2پیام سرویسرویداد افزوده شدن کاربر جدید به گروه
userKickedService 3پیام سرویسرویداد اخراج کاربر از گروه
userLeftService 4پیام سرویسرویداد ترک گروه توسط عضو
connectedLifecycleسوکتاتصال موفق به سرور WebSocket و شروع نشست کاربری
disconnectedLifecycleسوکتقطع ارتباط سوکت همراه با کد و دلیل قطع
statusLifecycleسوکتتغییر وضعیت کانکشن (CONNECTING, CONNECTED, ...)
errorErrorخطاهابروز هرگونه خطای شبکه، اعتبارسنجی یا سرور
updateUniversalسوکتدریافت فریم خام تمام به‌روزرسانی‌های ورودی سوکت

ویژگی‌ها و هلپرهای عملیاتی پیشرفته رویداد message

شیء دریافتی در رویداد message مجهز به ده‌ها پرچم نوع محتوا و توابع عملیاتی جهت پاسخگویی سریع، واکنش، باز کردن پاکت هدیه و مدیریت پیام است:

JavaScript
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();
});

کد نمونه شنونده‌های دسته‌های مختلف رویدادهای زنده سوکت

JavaScript
// ۱. رویدادهای ویرایش، حذف و پیام پین‌شده
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) آخرین گفتگوها، گروه‌ها و کانال‌های کاربر را همراه با آخرین پیام بارگذاری می‌نماید:

JavaScript
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):

JavaScript
// دریافت ۵۰ پیام آخر
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)

JavaScript
await client.sendPhoto(peerId, {
  fileId: 1048576,
  accessHash: 9876543210123456n,
  fileSize: 245000,
  name: 'image.jpg',
  width: 1280,
  height: 720,
  caption: 'تصویر ارسالی از BaleX 📸'
});

ارسال پیام صوتی و ویس (sendVoice)

JavaScript
await client.sendVoice(peerId, {
  fileId: 2097152,
  accessHash: 8765432109876543n,
  fileSize: 64000,
  duration: 12, // ۱۲ ثانیه
  waveForm: Buffer.from([0x01, 0x05, 0x1a, 0x22, 0x08]),
  caption: 'پیام صوتی راهنما 🎙️'
});

ارسال موزیک و آهنگ (sendAudio)

JavaScript
await client.sendAudio(peerId, {
  fileId: 3145728,
  accessHash: 7654321098765432n,
  fileSize: 5240000,
  duration: 215, // ثانیه
  name: 'track.mp3',
  title: 'قطعه موسیقی زیبا',
  performer: 'نام هنرمند',
  caption: 'موزیک ارسالی 🎵'
});

ارسال ویدیو (sendVideo)

JavaScript
await client.sendVideo(peerId, {
  fileId: 4194304,
  accessHash: 6543210987654321n,
  fileSize: 15400000,
  width: 1920,
  height: 1080,
  duration: 45,
  name: 'video.mp4',
  caption: 'ویدیوی معرفی محصول 🎬'
});

ارسال فایل و اسناد (sendDocument)

JavaScript
await client.sendDocument(peerId, {
  fileId: 5242880,
  accessHash: 5432109876543210n,
  fileSize: 1200000,
  name: 'report.pdf',
  mimeType: 'application/pdf',
  caption: 'گزارش نهایی پروژه 📄'
});

ارسال استیکر بله (sendSticker)

JavaScript
await client.sendSticker(peerId, 102456, 1234567890n, 100);
console.log('استیکر ارسال شد!');

مدیریت پیام‌ها و گفتگوها

ویرایش پیام (editMessage)

JavaScript
await client.editMessage(peerId, 104523n, 'متن اصلاح‌شده جدید ✏️');
console.log('پیام ویرایش شد.');

فوروارد پیام‌ها (forwardMessages)

JavaScript
const toPeer = 123456789;
const fromPeer = 987654321;
const messageIds = [1001n, 1002n];

await client.forwardMessages(toPeer, fromPeer, messageIds);
console.log('پیام‌ها فوروارد شدند.');

پین کردن پیام (pinMessage)

JavaScript
await client.pinMessage(peerId, 104523n);
console.log('پیام در بالای چت سنجاق شد 📌');

حذف پیام‌ها (deleteMessages)

JavaScript
await client.deleteMessages(peerId, [1001n, 1002n]);
console.log('پیام‌های مشخص‌شده حذف شدند 🗑️');

پاکسازی کل تاریخچه چت (clearChat)

JavaScript
await client.clearChat(peerId);
console.log('کل تاریخچه مکالمه پاکسازی گردید.');

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

ساخت گروه جدید (createGroup)

JavaScript
const newGroup = await client.createGroup('تیم برنامه‌نویسی BaleX', [
  123456789,
  987654321
]);
console.log('گروه ساخته شد با شناسه:', newGroup.group?.id);

افزودن عضو به گروه (inviteMembers)

JavaScript
await client.inviteMembers(groupId, [1122334455]);
console.log('عضو جدید به گروه افزوده شد.');

اخراج عضو از گروه (kickMember)

JavaScript
await client.kickMember(groupId, 1122334455);
console.log('کاربر از گروه اخراج شد.');

تغییر نام گروه (setGroupTitle)

JavaScript
await client.setGroupTitle(groupId, 'نام جدید و رسمی گروه');
console.log('عنوان گروه به‌روز شد.');

ترک گروه (leaveGroup)

JavaScript
await client.leaveGroup(groupId);
console.log('با موفقیت از گروه خارج شدید.');

کاربران، مخاطبین و پروفایل

مشخصات پروفایل کاربر (getUser)

JavaScript
const user = await client.getUser(123456789);
console.log('نام:', user.name);
console.log('نام کاربری:', user.username);
console.log('درباره من:', user.about);

اطلاعات گروه (getGroup)

JavaScript
const group = await client.getGroup(groupId);
console.log('عنوان گروه:', group.title);
console.log('تعداد اعضا:', group.membersCount);

لیست مخاطبین بله (getContacts)

JavaScript
const contacts = await client.getContacts();
contacts.users?.forEach(c => {
  console.log(`مخاطب: ${c.name} | شماره: ${c.phone} | شناسه: ${c.id}`);
});

افزودن مخاطب به حساب (addContact / addContactByUid)

افزودن از طریق شماره تلفن یا شناسه مستقیم کاربری (UID):

JavaScript
// روش ۱: افزودن با شماره موبایل و نام دلخواه
await client.addContact('09120000000', 'علی محمدی');

// روش ۲: افزودن مستقیم با شناسه کاربری (UID)
await client.addContactByUid(123456789);
console.log('مخاطب با موفقیت به حساب کاربری اضافه شد.');

همگام‌سازی و واردسازی گروهی (importContacts)

وارد کردن لیست کامل مخاطبین به طور یکجا (Bulk Sync):

JavaScript
const res = await client.importContacts([
  { phone: '09121111111', name: 'مهندس رضایی' },
  { phone: '09122222222', name: 'خانم عباسی' },
  { phone: '09123333333', name: 'پشتیبانی فنی' }
]);
console.log('مخاطبین بله‌ای همگام‌شده:', res.users?.length);

حذف مخاطب (removeContact)

JavaScript
await client.removeContact(123456789);
console.log('مخاطب از لیست دفترچه تلفن حذف شد.');

ویرایش مشخصات حساب (editName / editAbout)

JavaScript
// ویرایش نام نمایشی
await client.editName('توسعه‌دهنده BaleX');

// ویرایش متن درباره من (بیوگرافی)
await client.editAbout('یوزربات هوشمند و اتوماسیون پیشرفته بر بستر بله');
console.log('اطلاعات پروفایل به‌روزرسانی شد.');

مدیریت نام‌کاربری (editUsername / checkUsername)

JavaScript
// بررسی در دسترس بودن آیدی
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)

JavaScript
// مسدود کردن کاربر اسپمر
await client.blockUser(123456789);

// رفع مسدودی کاربر
await client.unblockUser(123456789);

// دریافت لیست کامل افراد بلاک‌شده
const blocked = await client.loadBlockedUsers();
console.log('لیست سیاه:', blocked.users);

واکنش‌ها و پوشه‌ها

ثبت واکنش ایموجی (setReaction)

JavaScript
// ثبت ایموجی لایک، قلب، آتش و... روی پیام
await client.setReaction(peerId, 104523n, '❤️');
console.log('ری‌اکشن ثبت شد!');

حذف واکنش از پیام (removeReaction)

JavaScript
await client.removeReaction(peerId, 104523n, '❤️');
console.log('ری‌اکشن حذف گردید.');

مشاهده آمار واکنش‌های پیام (getReactions)

JavaScript
const data = await client.getReactions(peerId, [104523n]);
console.log('آمار واکنش‌ها:', data.results);

مدیریت پوشه‌های چت (createFolder / loadFolders / deleteFolder)

JavaScript
// ۱. دریافت لیست پوشه‌ها
const folders = await client.loadFolders();
console.log('پوشه‌های من:', folders);

// ۲. ساخت پوشه جدید با دسته‌بندی چت‌ها
const newFolder = await client.createFolder('کانال‌های خبری', [
  123456,
  789101
]);

// ۳. حذف یک پوشه
await client.deleteFolder(newFolder.folderId);

نظرسنجی، کیف‌پول و ربات‌ها

ارسال نظرسنجی و کوییز (sendPoll)

JavaScript
await client.sendPoll(peerId, 'بهترین زبان برنامه‌نویسی برای بک‌اند چیست؟', [
  'JavaScript / Node.js',
  'Go (Golang)',
  'Python',
  'Rust'
], {
  isAnonymous: true,        // نظرسنجی ناشناس
  isMultipleChoice: false,  // چند گزینه‌ای
  isQuiz: false             // حالت کوییز و مسابقه
});

مدیریت نظرسنجی (createPoll / getPollResults / closePoll)

JavaScript
// دریافت نتایج آرای نظرسنجی
const results = await client.getPollResults(pollId);
console.log('نتایج آرا:', results);

// بستن و پایان پذیرش آرا در نظرسنجی
await client.closePoll(pollId);
console.log('نظرسنجی با موفقیت بسته شد.');

استعلام کیف پول و امتیازات بله (getWalletCredit / getWalletPoints)

JavaScript
// موجودی کیف‌پول ریالی
const credit = await client.getWalletCredit();
console.log('موجودی کیف‌پول:', credit);

// موجودی امتیازات بله
const points = await client.getWalletPoints();
console.log('امتیازات کسب‌شده:', points.balance);

کلیک روی دکمه شیشه‌ای ربات (sendInlineCallback)

JavaScript
// شبیه‌سازی کلیک کاربر روی اینلاین کیبورد ربات
await client.sendInlineCallback(botPeerId, messageId, 'action_confirm_pay');
console.log('کلیک دکمه اینلاین شبیه‌سازی شد.');

پاکت هدیه معمولی نقدی (Cash Gift Packet)

قابلیت ارسال پاکت هدیه ریالی با کسر از موجودی کیف‌پول (بر بستر bale.giftpacket.v1.GiftPacket):

ارسال پاکت هدیه نقدی (sendGiftPacket)

ارسال پاکت هدیه به چت یا گروه با امکان تقسیم مساوی یا شانسی میان افراد:

JavaScript
// ارسال پاکت هدیه ۵۰۰ هزار ریالی بین ۵ نفر به صورت شانسی
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)

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

JavaScript
// ۱. باز کردن و دریافت سهم نقدی (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)

JavaScript
const goldPacket = await client.sendGoldGiftPacket({
  peer: 123456789,
  amountMilligrams: 100,      // ۱۰۰ میلی‌گرم طلا
  count: 3,                   // ۳ برنده
  message: 'هدیه طلای بله تقدیم به شما! 🪙',
  givingType: 0               // ۰: شانسی، ۱: مساوی
});

console.log('شناسه پاکت طلای ارسالی:', goldPacket.giftPacketId);

باز کردن پاکت طلا و دریافت لیست برندگان (openGoldGiftPacket / claimGoldGiftPacket / getGoldWinners)

JavaScript
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)

JavaScript
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 آماده می‌سازد:

JavaScript
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 برای دریافت آدرس وب‌اپ با امضای سرور:

JavaScript
const { url, queryId } = await client.getMiniAppUrl({
  botUserId: botId,
  screenMode: 1, // ۱: تمام‌صفحه (Fullscreen)، ۰: پیش‌فرض
  directLink: 'start_param_value'
});

console.log('لینک اجرای وب‌اپ:', url);

دریافت هش امنیتی وب‌اپ (getWebappHash)

متد bale.ketf.v1.Ketf.GetWebappHash جهت دریافت هش رمزی اختصاصی ربات برای تایید کاربر:

JavaScript
const hashInfo = await client.getWebappHash(botId, 'custom_payload');
console.log('هش امنیتی:', hashInfo.hash);
console.log('شناسه کوئری:', hashInfo.queryId);
console.log('تاریخ احراز هویت:', hashInfo.authDate);

ارسال داده از مینی‌اپ به ربات (sendMiniAppData)

رویداد sendData برای ارسال نتیجه تراکنش یا امتیاز از مینی‌اپ به ربات:

JavaScript
await client.sendMiniAppData({
  botUserId: botId,
  queryId: hashInfo.queryId,
  data: { score: 150, action: 'game_finished' },
  buttonText: 'تایید و ادامه'
});

console.log('داده‌های وب‌اپ با موفقیت به ربات ارسال شد.');

تنظیمات دکمه منو و متدهای سفارشی مینی‌اپ

JavaScript
// ۱. دریافت تنظیمات دکمه منوی ربات (Menu Button)
const menuBtn = await client.getBotMenuButton(botId);
console.log('نوع دکمه منو:', menuBtn);

// ۲. اجرای متد سفارشی مینی‌اپ
const customRes = await client.invokeMiniAppCustomMethod({
  botUserId: botId,
  method: 'getUserTier',
  params: { userId: 123456 }
});
console.log('پاسخ متد سفارشی:', customRes);

بازوهای رسمی بله (Bale HTTP Bot API - docs.bale.ai)

پشتیبانی کامل و استاندارد بدون نیاز به پیش‌نیازهای سنگین از API رسمی بازوهای بله (docs.bale.ai). این کلاس به شما امکان می‌دهد ربات‌های رسمی با توکن دریافتی از @botfather در بله بسازید، رویدادها را دریافت کرده و انواع پیام‌ها، کیبوردها و فاکتورهای پرداخت الکترونیکی را مدیریت کنید.

نحوه دریافت توکن و آدرس پایه API

برای شروع، وارد پیام‌رسان بله شده و به بازوی رسمی @botfather پیام دهید. پس از ایجاد بازو، یک توکن اختصاصی شبیه به 123456789:abcdIuZmK5qNEm2A1BhUaAg7MPJv1O9KCcBQB2ro دریافت می‌کنید.
آدرس فراخوانی متدها: https://tapi.bale.ai/bot<token>/<methodName>
آدرس دانلود فایل‌ها: https://tapi.bale.ai/file/bot<token>/<file_path>

JavaScript (BaleBot Quickstart)
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> - توجه مهم
JavaScript (Text Formatting Example)
// روش ۱: ارسال پیام با حالت 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)

بازوی بله از دو شیوه استاندارد برای تحویل رویدادهای زنده کاربران بهره می‌برد:

JavaScript (Polling & Webhook Server)
// ۱. شیوه لانگ پولینگ (مناسب سیستم‌های تست و سرورهای بدون دامنه عمومی)
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.

JavaScript (All Media Types & Upload Methods)
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 پیاده‌سازی رابط‌های کاربری تعاملی را بسیار ساده و روان کرده‌اند:

JavaScript (Interactive Keyboards & Callbacks)
// ۱. کیبورد شیشه‌ای (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)

مجموعه کامل متدهای مدیریتی برای اخراج، ارتقای مدیران، تنظیم اطلاعات و لینک‌های دعوت در گروه‌ها و کانال‌های بله:

JavaScript (Chat & Member 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)

عملیات روی پیام‌های ارسال‌شده و متد اختصاصی پلتفرم بله برای ثبت امتیاز کاربر:

JavaScript (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۵۱۲ پیکسل دارند:

JavaScript (Stickers API)
// ۱. آپلود فایل استیکر 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)

پلتفرم مالی بله امکان صدور فاکتور ریالی مستقیم و کسر وجه از کیف‌پول یا درگاه شتابی را فراهم می‌کند:

JavaScript (Invoices & Payments)
// ۱. ارسال فاکتور پرداخت درون چت
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 برای ارسال، مشاهده و تعامل با استوری‌ها:

JavaScript
// ۱. انتشار استوری جدید
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):

JavaScript
// تنظیم ارسال پیام برای ۲ ساعت بعد
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)

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

JavaScript
// ۱. خلاصه‌سازی یک لینک یا صفحه با Bale TLDR
const summary = await client.summarizeLink('https://bale.ai');
console.log('خلاصه محتوا:', summary);

// ۲. پرسش از هوش مصنوعی تورینگ بله
const aiAnswer = await client.askAI('ساعت کاری شعب بانک در تعطیلات چگونه است؟');
console.log('پاسخ هوش مصنوعی:', aiAnswer);

بانکداری و خدمات مالی شتابی

استعلام نام صاحب کارت شتابی (inquireDestinationPan)

استعلام نام و نام خانوادگی دارنده حساب کارت مقصد قبل از واریز وجه:

JavaScript
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):

JavaScript
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)

JavaScript
const balance = await client.getCardBalance({
  sourcePan: '6037991812345678',
  pin2: '984512',
  cvv2: '345',
  expireDate: '0628'
});

console.log('موجودی کارت:', balance.balanceRials, 'ریال');
console.log('موجودی قابل برداشت:', balance.availableBalanceRials, 'ریال');

ارسال پاکت هدیه طلای بله (sendGoldPacket)

ارسال هدیه شمش طلا بر حسب میلی‌گرم در چت:

JavaScript
await client.sendGoldPacket({
  peerId: 123456789,
  goldMilligrams: 100, // ۱۰۰ میلی‌گرم طلا
  message: 'تبریک روز مهندس از طرف BaleX! 🎁',
  packetType: 0
});
console.log('پاکت طلایی با موفقیت ارسال شد.');

موتور حضور و ضد مسدودی (Presence & Stealth)

کنترل وضعیت آنلاین و تایپینگ (setOnline / sendTyping / stopTyping)

JavaScript
// ۱. ارسال وضعیت آنلاین (سبز شدن چراغ آنلاین در بله)
await client.setOnline(true);

// ۲. ارسال وضعیت "در حال نوشتن..." با توقف خودکار بعد از ۳ ثانیه
await client.sendTyping(peerId, 3000);

// ۳. توقف دستی تایپ
await client.stopTyping(peerId);

تنظیمات موتور ضد مسدودی در حین اجرا (Humanize Controls)

JavaScript
// فعال‌سازی حالت انسانی با تنظیمات اختصاصی
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 دلخواه استفاده نمایید:

JavaScript
// روش ۱: فراخوانی از طریق پراکسی خودکار سرویس
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.isConnectedbooleanوضعیت فعال بودن اتصال زنده سوکت.
احراز هویتclient.meUserاطلاعات نمایه کاربر متصل فعلی.
پیام‌رسانی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.isHumanizedbooleanوضعیت فعال بودن تنظیمات رفتار انسانی.
عمومیclient.sleep(ms)Promise<void>تاخیر زمانی در صف درخواست‌ها بدون اشغال CPU.
پروتکل باینریclient.invoke(service, method, payload, meta)Promise<any>فراخوانی مستقیم و سطح وایر هر متد از ۶۳۶ متد بله.

کاتالوگ کامل ۵۳ سرویس بله در ۱۰ حوزه کاربردی

تفکیک جامع تمامی ۵۳ سرویس رسمی استخراج شده از پروتکل کلاینت وب بله همراه با تعداد متدها و شرح کاربرد:

۱. احراز هویت، امنیت و تنظیمات (۴ سرویس، ۳۸ متد)

نام کامل سرویسپراکسی (Namespace)متدهاتوضیحات
bale.auth.v1.Authclient.auth27ورود، تایید کد، رمز دومرحله‌ای، خروج، مدیریت نشست‌ها و لغو نشست‌های موازی
bale.ramz.v1.Ramzclient.ramz7سیستم تولید، دریافت و اعتبارسنجی رمز دوم یکبار مصرف و پویا (OTP) شتاب
bale.v1.Configsclient.configs3دریافت پیکربندی عمومی سرورها، نسخه‌های فعال و پارامترهای پروتکل
bale.llm_auth.v1.LLMAuthServiceclient.lLMAuth1احراز هویت و دریافت کلید دسترسی به مدل‌های زبانی هوش مصنوعی بله

۲. پیام‌رسانی، استریم و محتوا (۶ سرویس، ۵۶ متد)

نام کامل سرویسپراکسی (Namespace)متدهاتوضیحات
bale.messaging.v2.Messagingclient.messaging43ارسال، ویرایش، حذف، فوروارد، پین، پوشه‌ها و بارگذاری تاریخچه چت‌ها
bale.schedule.v1.Schedulerclient.scheduler6زمان‌بندی ارسال پیام در آینده، لغو یا ویرایش زمان ارسال خودکار
bale.tldr.v1.TLDRclient.tLDR2خلاصه‌سازی خودکار گفتگوها و پیام‌های طولانی کانال‌ها با هوش مصنوعی
bale.turing.v1.AIclient.aI2ارسال پرامپت و دریافت پاسخ بلادرنگ از موتورهای زبانی هوش مصنوعی تورینگ
bale.message_stream.v1.MessageStreamclient.messageStream2استریم بلادرنگ پیام‌ها و فیدهای خبری
bale.maviz.v1.MavizStreamclient.mavizStream4استریم بسته‌های باینری سوکت ماویز و هماهنگ‌سازی داده‌ها

۳. کاربران، مخاطبین و حضور آنلاین (۵ سرویس، ۵۲ متد)

نام کامل سرویسپراکسی (Namespace)متدهاتوضیحات
bale.users.v1.Usersclient.users36پروفایل کامل، نام، بیو، نام کاربری، دفترچه مخاطبین و مدیریت لیست سیاه
bale.presence.v1.Presenceclient.presence11وضعیت آنلاین بودن، زمان آخرین بازدید، ارسال وضعیت تایپینگ و اشتراک وضعیت
bale.anonymous_contact.v1.AnonymousContactclient.anonymousContact1برقراری تماس امن صوتی بدون آشکارسازی شماره تلفن همراه
bale.organizations.v1.Organizationsclient.organizations2پروفایل شرکتی، تایید هویت سازمانی و نشان‌های تایید
bale.top_peer.v1.TopPeerclient.topPeer2محاسبه و دریافت لیست مخاطبین و چت‌های پرتکرار کاربر

۴. گروه‌ها، کانال‌ها و کاوش (۵ سرویس، ۶۸ متد)

نام کامل سرویسپراکسی (Namespace)متدهاتوضیحات
bale.groups.v1.Groupsclient.groups50ایجاد گروه، لینک دعوت، تغییر ادمین، اخراج و تنظیم دسترسی‌های اعضا
bale.charnet.v1.CharnetServiceclient.charnet11جستجو، معرفی کانال‌ها، لیست چهارسو و دسته‌بندی موضوعی
bale.recommender.v1.Recommenderclient.recommender4موتور پیشنهاد هوشمند کانال‌ها، چت‌ها و محتوای مرتبط
bale.falake.v1.Falakeclient.falake1بخش کاوش و فید محتواهای پرطرفدار و ترند فلکه
bale.fanoos.v1.fanoosclient.fanoos2سیستم کاوش و پیشنهاد هوشمند فانوس

۵. خدمات بانکی شتابی و ساب (۴ سرویس، ۳۷ متد)

نام کامل سرویسپراکسی (Namespace)متدهاتوضیحات
bale.bank.v1.Bankclient.bank17استعلام کارت مقصد، انتقال کارت به کارت، موجودی و گردش حساب شتاب
bale.sap.v1.Sapclient.sap16سامانه پرداخت، قبض، استعلام تراکنش‌های شاپرک و خدمات ساب
bale.microbanki.v1.MicroBankiclient.microBanki3تسهیلات و خدمات خرد بانکی و استعلام تسهیلات
bale.my_bank.v1.MyBankclient.myBank1شعب، اطلاعات و حساب‌های متمرکز بانک ملی

۶. کیف‌پول، طلا و امور مالی (۷ سرویس، ۶۵ متد)

نام کامل سرویسپراکسی (Namespace)متدهاتوضیحات
bale.kifpool.v1.Kifpoolclient.kifpool30کیف پول‌های ریالی، گردش موجودی، امتیازات بله و باشگاه مشتریان
bale.wallet.v1.Walletclient.wallet13شارژ کیف پول، تسویه و برداشت وجه به حساب بانکی
bale.pfm.v1.Pfmclient.pfm15مدیریت مالی شخصی، دسته‌بندی هزینه‌ها و نمودار دخل و خرج
bale.giftpacket.v1.GiftPacketclient.giftPacket3ارسال پاکت هدیه ریالی به شکل مساوی یا شانسی در گروه‌ها
bale.balebank.v1.GoldGiftPacketclient.goldGiftPacket3ارسال، دریافت و بازگشایی پاکت هدیه شمش طلا
bale.balebank.v1.GoldWalletclient.goldWallet1موجودی و گردش حساب طلایی بله‌بانک
bale.crowdfunding.v1.CrowdFundingclient.crowdFunding2پویش‌های جمع‌سپاری مالی، نیکوکاری و خیریه

۷. ربات‌ها، خدمات و ابزارک‌ها (۵ سرویس، ۳۱ متد)

نام کامل سرویسپراکسی (Namespace)متدهاتوضیحات
bale.ketf.v1.Ketfclient.ketf14پلتفرم ربات‌ها، کلیک دکمه‌های اینلاین، دستورات و هوک‌ها
bale.garson.v1.Garsonclient.garson11سامانه سفارش خدمات و غذا، مدیریت میز و پرداخت گارسون
bale.appzar.v1.Appzarclient.appzar3ابزارک‌ها و مینی‌اپلیکیشن‌های درون‌برنامه‌ای
bale.timche.v1.Timcheclient.timche5سامانه فروشگاهی تیمچه و خدمات تجاری
bale.ghasedak.v1.GhasedakServiceclient.ghasedak2ارسال نوتیفیکیشن و پیامک‌های سامانه قاصدک

۸. رسانه، استوری، جلسات و صوت (۶ سرویس، ۷۹ متد)

نام کامل سرویسپراکسی (Namespace)متدهاتوضیحات
bale.story.v1.Storyclient.story24ارسال، مشاهده، استوری ۲۴ ساعته و آمار بازدیدکنندگان
bale.meet.v1.Meetclient.meet30جلسات صوتی و تصویری آنلاین، اشتراک تصویر و کنترل میکروفن
bale.v1.Imagesclient.images10مدیریت تصاویر، برش عکس و سایزهای آواتار پروفایل
ai.bale.server.Filesclient.files7دریافت لینک مستقیم آپلود و دانلود فایل‌ها از سرور نسیم
bale.shared_media.v1.SharedMediaServiceclient.sharedMedia2دریافت تاریخچه تمام عکس‌ها، فایل‌ها و لینک‌های ردوبدل شده
bale.pishvaz.v1.Pishvazclient.pishvaz3آوای پیشواز تماس و پخش نمونه‌های صوتی

۹. واکنش‌ها، نظرسنجی و پشتیبانی (۵ سرویس، ۱۹ متد)

نام کامل سرویسپراکسی (Namespace)متدهاتوضیحات
bale.abacus.v1.Abacusclient.abacus9ثبت، دریافت و مدیریت ری‌اکشن‌های ایموجی روی پیام‌ها
bale.poll.v1.Pollclient.poll5ساخت نظرسنجی، کوییزهای چندگزینه‌ای و بستن نظرسنجی
bale.feedback.v1.FeedBackclient.feedBack1ارسال فیدبک، نظرات و پیشنهادها به تیم توسعه بله
bale.report.v1.Reportclient.report2گزارش اسپم، کلاهبرداری یا تخلف محتوا
bale.negah.v1.Negahclient.negah1سرویس نظارت و ثبت رویدادهای نگاه

۱۰. تبلیغات، فروشگاه و خدمات ویژه (۵ سرویس، ۱۷۴ متد)

نام کامل سرویسپراکسی (Namespace)متدهاتوضیحات
bale.advertisement.v1.Advertisementclient.advertisement126سیستم تبلیغات بله، رزرو جایگاه، بودجه و کمپین‌ها
bale.market.v1.Marketclient.market26فروشگاه کالا، ثبت سفارش و رهگیری سبد خرید
bale.search.v1.Searchclient.search12موتور جستجوی سراسری پیام‌ها، کاربران، کانال‌ها و فایل‌ها
bale.premium.v1.Premiumclient.premium7اشتراک پریمیوم، استیکرهای انحصاری و افزایش محدودیت‌ها
bale.magazine.v1.Magazineclient.magazine9پایگاه اخبار و مقالات مجله بله

جستجوگر تعاملی تمامی ۶۳۶ متد رسمی بله (Live Method Explorer)

می‌توانید در کادر زیر هر یک از ۶۳۶ متد رسمی بله را جستجو کرده یا بر اساس دسته‌بندی فیلتر نمایید تا کد فراخوانی آن آماده کپی شود:

در حال آماده‌سازی...
همه متدها (۶۳۶) پیام‌رسانی احراز هویت بانکی و شتاب کیف پول و طلا کاربران و مخاطبین گروه‌ها و کانال‌ها حضور و Presence واکنش‌ها (Abacus) نظرسنجی (Poll) ربات‌ها (Ketf) استوری و رسانه تبلیغات (Ads) هوش مصنوعی (AI)

جدول کدهای خطای سرور بله و راهکارها

کد خطای 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) کتابخانه برای ارسال دستورات و دریافت رویدادها استفاده کنید.

دو روش اتصال از Go:
۱. پل پرسرعت STDIO (os/exec): اجرای مستقیم به صورت زیرپروسس با تاخیر صفر نانوثانیه‌ای و بدون اشغال پورت شبکه.
۲. پل سرور HTTP / JSON-RPC: برقراری ارتباط از طریق ارسال درخواست‌های استاندارد HTTP REST به صورت میکروسرویس مستقل.

روش اول: اجرای مستقیم از Go با Subprocess (STDIO)

کد کامل زبان Go برای اجرای پروسس و ارسال دستورات بدون نیاز به وب‌سرور:

Go (Golang)
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

ابتدا پل را در پس‌زمینه با دستور زیر اجرا کنید:

Terminal
# اجرای سرور پل ارتباطی روی پورت ۸۷۶۵
npx balex bridge --port 8765

سپس در هر پروژه Go با پکیج استاندارد net/http به آن متصل شوید:

Go (Golang)
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)
}