sajaddp / laravel-bale

v1.0.0 2026-09-18 19:51 UTC

Requires

• php: ^8.3
• illuminate/http: ^13.0
• illuminate/support: ^13.0

Requires (Dev)

• larastan/larastan: ^3.9
• laravel/pint: ^1.29
• orchestra/testbench: ^11.0
• pestphp/pest: ^4.6
• pestphp/pest-plugin-laravel: ^4.1
• phpstan/extension-installer: ^1.4

MIT

• Sajad Dehshiri

• laravel
• chatbot
• laravel-package
• Bale
• bot-api
• bale-bot
• bale-messenger
• bale-bot-api

Published on Packagist.org on 2026-09-18 19:54 UTC

README

لاراول بله، با نام پکیج sajaddp/laravel-bale، راه کار با بازوی بله از داخل برنامه‌های لاراول است. با آن پیام، رسانه و فایل می‌فرستید، به کاربران پاسخ می‌دهید، دکمهٔ تعاملی می‌سازید و رویدادهای دریافتی بازو را در برنامهٔ خود به کار می‌گیرید.

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

مستندات فارسی لاراول بله · شروع کار · آزمون بدون ارسال واقعی · کدنویسی با هوش مصنوعی · فهرست متدها

امکانات اصلی

نیاز شما	امکان پکیج
ارسال پیام و پاسخ به کاربر	ارسال متن، پاسخ به پیام، ویرایش، کپی، بازفرستادن و حذف پیام
فرستادن و دریافت فایل	ارسال عکس، سند، صدا و ویدیو؛ آپلود فایل محلی؛ استفادهٔ دوباره از فایل بله؛ دانلود محتوای فایل
ساخت تعامل با کاربر	دکمه‌های درون‌خطی، پاسخ به کلیک کاربر و درخواست ثبت نظر با askReview
دریافت پیام‌های بازو	تنظیم وب‌هوک یا دریافت رویدادها با getUpdates
آزمایش اتصال در برنامهٔ لاراول	شبیه‌سازی درخواست‌ها با Bale::fake() و بررسی ارسال‌ها بدون ارتباط واقعی با بله
استفاده همراه ابزارهای هوش مصنوعی	راهنما و مهارت اختصاصی لاراول بوست، همراه با مرجع متدها و نمونه‌های قابل‌استفاده

نسخهٔ فعلی ۲۵ متد رسمی بله، ۲ متد کمکی و ۵ ابزار آزمون دارد. جدول پوشش رابط بله مشخص می‌کند کدام متدهای رسمی پیاده‌سازی شده‌اند و کدام هنوز پشتیبانی نمی‌شوند.

نصب در لاراول و ارسال نخستین پیام

نیازمندی‌ها

مورد	مقدار
لاراول	نسخهٔ ۱۳
پی‌اچ‌پی	نسخهٔ ۸.۳ یا بالاتر در شاخهٔ ۸
نام پکیج	sajaddp/laravel-bale
مجوز	ام‌آی‌تی

نصب پکیج

composer require sajaddp/laravel-bale

ساخت ربات و تنظیم توکن

طبق راهنمای رسمی ساخت بازوی بله، ربات را از طریق بازوی پدر بسازید و توکن آن را دریافت کنید. «بازو» نامی هست که بله برای ربات‌های خود به کار می‌برد.

توکن را در فایل .env برنامه قرار دهید؛ آن را در کد، مخزن یا گزارش عمومی منتشر نکنید:

BALE_BOT_TOKEN=your-bot-token

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

php artisan vendor:publish --tag=bale-config

ارسال پیام

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

use Sajaddp\Bale\Facades\Bale;

$message = Bale::sendMessage(
    chatId: 123456789,
    text: 'گزارش شما آماده شد.',
);

نتیجه، آرایهٔ پیام ارسال‌شده هست. برای بررسی توکن و دریافت مشخصات ربات نیز می‌توانید Bale::getMe() را فراخوانی کنید. مقصد پیام، شناسهٔ عددی گفتگو یا نام کاربری کانال با قالبی مانند @channelname هست؛ شرایط دسترسی مقصد تابع مقررات بله باقی می‌ماند.

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

لاراول بله راهنمای استفاده و مهارت اختصاصی bale-development را همراه پکیج ارائه می‌کند. این منابع، متدهای موجود، ورودی‌ها، ارسال فایل و روش آزمون را در اختیار ابزار کدنویسی قرار می‌دهند تا برای کار با پکیج، نمونه و قرارداد مشخص داشته باشد.

پس از نصب پکیج، در محیط توسعهٔ برنامهٔ لاراول اجرا کنید:

composer require laravel/boost --dev
php artisan boost:install

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

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

برای شروع می‌توانید از ابزار خود بخواهید:

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

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

چطور کد ربات را بدون ارسال پیام واقعی آزمون کنیم؟

در محیط آزمون لاراول، یک توکن آزمایشی تنظیم کنید و پیش از اجرای کدی که با بله ارتباط دارد، Bale::fake() را فراخوانی کنید:

use Sajaddp\Bale\Facades\Bale;

config(['bale.token' => 'test-token']);
Bale::fake();

Bale::sendMessage(
    chatId: 123456789,
    text: 'گزارش شما آماده شد.',
);

Bale::assertSent('sendMessage', [
    'chat_id' => 123456789,
    'text' => 'گزارش شما آماده شد.',
]);
Bale::assertSentTimes('sendMessage', 1);
Bale::assertNotSent('sendDocument');

در این نمونه پیام واقعی ارسال نمی‌شود. در آزمون برنامهٔ خود، به‌جای فراخوانی مستقیم sendMessage، بخشی از برنامه را اجرا کنید که باید پیام بفرستد؛ سپس مقصد، متن و تعداد درخواست‌ها را بررسی کنید.

ابزار آزمون	کاربرد
Bale::fake()	شبیه‌سازی درخواست‌های بله برای توکن تنظیم‌شده
Bale::assertSent()	بررسی ارسال یک متد، با امکان بررسی داده‌ها یا استفاده از تابع شرط
Bale::assertSentTimes()	بررسی تعداد ارسال‌های یک متد
Bale::assertNotSent()	بررسی ارسال‌نشدن یک متد یا درخواست مطابق شرط
Bale::assertNothingSent()	بررسی اینکه هیچ درخواست بله‌ای ثبت نشده باشد

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

برای ترکیب با شبیه‌سازی فراگیر لاراول، ابتدا Bale::fake() و سپس Http::fake() بدون آرگومان یا دارای الگوی '*' را ثبت کنید. شبیه‌سازی‌های محدود به نشانی سرویس‌های دیگر، در صورتی که نشانی بله را شامل نشوند، در هر ترتیب قابل‌استفاده‌اند.

این بررسی‌ها نام متد رسمی را می‌بینند: پاسخ‌دادن با replyToMessage را با assertSent('sendMessage') بررسی کنید. برای پاسخ خطای دلخواه یا آزمون جزئیات ارسال فایل، راهنمای آزمون را ببینید.

چطور به پیام کاربر پاسخ بدهیم؟

وقتی آرایهٔ پیام دریافتی را دارید، replyToMessage شناسهٔ گفتگو و شناسهٔ همان پیام را استخراج و پاسخ را ارسال می‌کند:

use Sajaddp\Bale\Facades\Bale;

Bale::replyToMessage(
    message: $update['message'],
    text: 'پیام شما دریافت شد.',
);

فیلدهای message_id و chat.id باید عدد صحیح باشند. ورودی ناقص پیش از ارسال درخواست با InvalidArgumentException رد می‌شود.

این متد کمکی بر پایهٔ sendMessage و reply_to_message_id کار می‌کند. مقصد، متن و شناسهٔ پیام پاسخ‌داده‌شده با گزینه‌های اضافی قابل جایگزینی نیستند. راهنمای ارسال و مدیریت پیام

چطور فایل، عکس و ویدیو بفرستیم؟

برای ارسال فایل، تفاوت ورودی‌ها مهم هست:

ورودی	رفتار
شناسهٔ فایل بله در قالب رشته	استفادهٔ دوباره از فایل موجود با file_id
نشانی اینترنتی در قالب رشته	ارسال نشانی به بله برای دریافت فایل، مطابق محدودیت‌های همان متد
شیء SplFileInfo	آپلود صریح فایل محلی

مسیر محلی در قالب رشته به‌صورت خودکار آپلود نمی‌شود. برای نمونه:

use Sajaddp\Bale\Facades\Bale;

// آپلود فایل محلی
Bale::sendDocument(
    chatId: 123456789,
    document: new \SplFileInfo(storage_path('app/report.pdf')),
    options: ['caption' => 'گزارش آماده‌شده'],
);

// استفادهٔ دوباره از فایل موجود در بله
Bale::sendDocument(
    chatId: 123456789,
    document: 'bale-file-id',
);

// ارسال ویدیو از نشانی اینترنتی
Bale::sendVideo(
    chatId: 123456789,
    video: 'https://example.com/video.mp4',
);

برای عکس از sendPhoto، برای فایل صوتی از sendAudio، برای پیام صوتی از sendVoice و برای پویانمایی از sendAnimation استفاده کنید. امضای sendPhoto در این پکیج، مطابق جدول فعلی مستندات بله، پارامتر الزامی fromChatId را نیز دارد؛ نمونهٔ دقیق در راهنمای فایل و رسانه آمده.

در sendMediaGroup، پیوست‌های محلی را با نام مشخص معرفی کنید و در آرایهٔ رسانه به همان نام با قالب attach://name ارجاع دهید. پکیج پیش از ارسال، وجود پیوست متناظر را بررسی می‌کند.

چطور فایل دریافتی از بله را دانلود و ذخیره کنیم؟

getFile اطلاعات فایل را می‌گیرد. متد کمکی downloadFile همین درخواست را انجام می‌دهد و سپس محتوای فایل را دانلود می‌کند:

use Illuminate\Support\Facades\Storage;
use Sajaddp\Bale\Facades\Bale;

$contents = Bale::downloadFile($fileId);

Storage::put('bale/report.pdf', $contents);

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

مطابق مستندات رسمی بله، سقف فعلی دانلود بازوها ۲۰ مگابایت و اعتبار تضمین‌شدهٔ لینک یک ساعت هست؛ پس از انقضا، دریافت دوبارهٔ اطلاعات فایل امکان گرفتن لینک جدید را فراهم می‌کند. پکیج این محدودیت حجم را به‌صورت محلی اعمال نمی‌کند. اگر اطلاعات فایل، file_path غیرخالی نداشته باشد، پیش از دانلود UnexpectedValueException رخ می‌دهد.

چطور دکمهٔ تعاملی بسازیم؟

دکمه‌های درون‌خطی را در reply_markup قرار دهید:

use Sajaddp\Bale\Facades\Bale;

Bale::sendMessage(
    chatId: 123456789,
    text: 'گزارش را دریافت کردید؟',
    options: [
        'reply_markup' => [
            'inline_keyboard' => [
                [
                    ['text' => 'بله، دریافت شد', 'callback_data' => 'report_received'],
                ],
            ],
        ],
    ],
);

هنگام دریافت رویداد کلیک، با answerCallbackQuery به آن پاسخ دهید. پیام همراه این رویداد اختیاری هست؛ فقط در صورت وجود آن، ویرایش پیام را انجام دهید:

use Sajaddp\Bale\Facades\Bale;

$callback = $update['callback_query'];

Bale::answerCallbackQuery(callbackQueryId: $callback['id']);

if (isset($callback['message'])) {
    Bale::editMessageText(
        chatId: $callback['message']['chat']['id'],
        messageId: $callback['message']['message_id'],
        text: 'دریافت گزارش تأیید شد.',
    );
}

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

دریافت پیام‌های ربات: وب‌هوک یا دریافت دوره‌ای

وب‌هوک در لاراول ۱۳

با وب‌هوک، بله رویدادها را به نشانی برنامهٔ شما می‌فرستد. مسیر دریافت در برنامهٔ لاراول تعریف می‌شود؛ برای نمونه در routes/web.php:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::post('/bale/webhook', function (Request $request) {
    $update = $request->all();

    // اعتبارسنجی و پردازش رویداد را در برنامهٔ خود انجام دهید.

    return response()->noContent();
});

در bootstrap/app.php، داخل تابع موجود withMiddleware، فقط همین مسیر را از بررسی جعل درخواست مستثنا کنید:

$middleware->preventRequestForgery(except: [
    'bale/webhook',
]);

این تنظیم، مطابق راهنمای امنیت درخواست در لاراول ۱۳، برای پذیرش درخواست خارجی لازم هست؛ به‌تنهایی اصالت فرستنده را اثبات نمی‌کند. اعتبارسنجی ورودی و جلوگیری از پردازش تکراری را متناسب با برنامهٔ خود پیاده‌سازی کنید.

پس از در دسترس قرارگرفتن برنامه روی یک دامنهٔ واقعی با اتصال امن، نشانی دقیق همین مسیر را ثبت کنید. دامنهٔ نمونه را با دامنهٔ برنامه جایگزین کنید:

use Sajaddp\Bale\Facades\Bale;

Bale::setWebhook('https://example.com/bale/webhook');

برای مشاهدهٔ تنظیمات از getWebhookInfo و برای حذف وب‌هوک از deleteWebhook استفاده کنید. راهنمای کامل وب‌هوک بله

دریافت دوره‌ای با getUpdates

getUpdates در هر فراخوانی فقط یک درخواست می‌فرستد:

use Sajaddp\Bale\Facades\Bale;

$updates = Bale::getUpdates([
    'limit' => 100,
    'timeout' => 30,
]);

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

درخواست ثبت نظر با askReview

این متد رسمی بله، درخواست نمایش فرم ثبت یا ویرایش نظر دربارهٔ ربات را ارسال می‌کند:

use Sajaddp\Bale\Facades\Bale;

Bale::askReview(
    userId: 123456789,
    delaySeconds: 30,
);

هر دو ورودی عدد صحیح و الزامی هستند. پاسخ موفق، مقدار منطقی درست هست؛ نمایش فرم همچنان به نسخهٔ برنامهٔ بله و شرایط اعلام‌شده از سوی بله بستگی دارد. مستند رسمی ثبت نظر

مرجع متدهای پشتیبانی‌شده

متدهای متناظر با رابط رسمی بله

این جدول قابلیت‌های موجود همین پکیج را نشان می‌دهد، نه تمام امکانات سرویس بله. جزئیات ورودی‌ها در مرجع کامل متدها و وضعیت سایر قابلیت‌ها در جدول پوشش بله آمده.

کاربرد	متد پکیج	خروجی
دریافت مشخصات ربات	getMe	آرایه
ارسال پیام متنی	sendMessage	آرایهٔ پیام
بازفرستادن پیام	forwardMessage	آرایهٔ پیام
کپی پیام	copyMessage	آرایهٔ شناسهٔ پیام
نمایش وضعیت گفتگو	sendChatAction	مقدار منطقی
ثبت یا حذف وب‌هوک	setWebhook، deleteWebhook	مقدار منطقی
دریافت اطلاعات وب‌هوک	getWebhookInfo	آرایه
دریافت رویدادها	getUpdates	آرایهٔ رویدادها
پاسخ به کلیک دکمه	answerCallbackQuery	مقدار منطقی
درخواست ثبت نظر	askReview	مقدار منطقی
ویرایش متن، زیرنویس یا دکمه‌ها	editMessageText، editMessageCaption، editMessageReplyMarkup	نتیجهٔ خام بله
حذف پیام	deleteMessage	مقدار منطقی
ارسال عکس، صدا، سند، ویدیو، پویانمایی و پیام صوتی	sendPhoto، sendAudio، sendDocument، sendVideo، sendAnimation، sendVoice	آرایهٔ پیام
ارسال گروه رسانه	sendMediaGroup	آرایهٔ پیام‌ها
دریافت اطلاعات فایل	getFile	آرایهٔ اطلاعات فایل
ارسال موقعیت جغرافیایی	sendLocation	آرایهٔ پیام
ارسال اطلاعات مخاطب	sendContact	آرایهٔ پیام

بله برای خروجی سه متد ویرایش پیام نوع مشخصی مستند نکرده؛ پکیج نتیجهٔ خام آن‌ها را برمی‌گرداند. در متدهای دارای options نیز ورودی‌های الزامیِ نام‌دار بر کلیدهای همنام در گزینه‌های اضافی مقدم هستند.

متدهای کمکی خود پکیج

متد	کاری که انجام می‌دهد	خروجی
replyToMessage	استخراج شناسه‌های پیام دریافتی و ارسال پاسخ با sendMessage	آرایهٔ پیام
downloadFile	دریافت اطلاعات با getFile و سپس دانلود فایل	رشتهٔ حاوی محتوای فایل

این دو متد، نام درخواست رسمی بله نیستند. ابزارهای آزمون نیز بخش جداگانه‌ای از پکیج هستند و در شمار ۲۵ متد رسمی قرار نمی‌گیرند.

خطاها را چطور تشخیص بدهیم؟

وضعیت	خطای قابل‌دریافت
بله درخواست را با ساختار خطای معتبر رد کرده	Sajaddp\Bale\Exceptions\BaleRequestException
پاسخ ناموفق شبکه خارج از ساختار معتبر خطای بله، از جمله دانلود ناموفق	Illuminate\Http\Client\RequestException
پاسخ موفق با ساختار نامعتبر یا اطلاعات ناقص فایل برای دانلود	UnexpectedValueException
ناتوانی در برقراری ارتباط یا پایان مهلت درخواست	Illuminate\Http\Client\ConnectionException
ورودی نامعتبر برای پاسخ به پیام یا پیوست محلی	InvalidArgumentException
توکن تنظیم نشده یا مقدار آن نامعتبر هست	LogicException

جزئیات خطای بله از خود استثنا قابل‌بررسی هست. برای عیب‌یابی، توکن ربات یا نشانی داخلی دانلود حاوی توکن را در گزارش عمومی قرار ندهید. راهنمای رفع اشکال و راهنمای رسمی خطاهای شبکه در لاراول

راهنماهای موضوعی

موضوع	راهنمای آنلاین	متن داخل مخزن
نصب و نخستین درخواست	شروع کار	راهنمای شروع
ارسال، پاسخ و ویرایش پیام	مدیریت پیام‌ها	متن راهنما
دریافت پیام با وب‌هوک	راه‌اندازی وب‌هوک	متن راهنما
دریافت دوره‌ای رویدادها	دریافت با getUpdates	متن راهنما
ارسال و دریافت فایل	فایل و رسانه	متن راهنما
دکمه‌ها و تعامل با کاربر	دکمه‌های درون‌خطی	متن راهنما
آزمون بدون ارتباط واقعی	آزمون پکیج	متن راهنما
نام، ورودی و خروجی متدها	مرجع کامل	مرجع داخل مخزن
قابلیت‌های موجود و پشتیبانی‌نشده	پوشش رابط بله	جدول داخل مخزن
نمونه‌های کوتاه	نمونه‌های کاربردی	متن نمونه‌ها
خطاها و پرسش‌های اجرایی	رفع اشکال	متن راهنما
استفاده با ابزارهای هوش مصنوعی	راهنمای هوش مصنوعی	متن راهنما

پرسش‌های متداول

آیا این پکیج تمام امکانات بله را پوشش می‌دهد؟

خیر. نسخهٔ فعلی ۲۵ متد رسمی را پوشش می‌دهد. وضعیت ۵۰ متد موجود در مستند مرجع بله، شامل ۲۵ متد پشتیبانی‌نشده، در جدول پوشش ثبت شده. پیش از انتخاب پکیج برای پرداخت، مدیریت گروه یا قابلیت‌های دیگر، همین جدول را بررسی کنید.

آیا برای لاراول ۱۲ هم قابل‌استفاده هست؟

محدودهٔ پشتیبانی فعلی فقط لاراول ۱۳ هست. پشتیبانی از نسخه‌های قدیمی‌تر اعلام نشده.

آیا راهنماهای ربات تلگرام برای این پکیج هم کاربرد دارند؟

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

آیا لاراول بوست برای اجرای ربات لازم هست؟

خیر. بوست برای کمک به کدنویسی با هوش مصنوعی در محیط توسعه استفاده می‌شود. اجرای ربات و ارسال درخواست به بله به آن وابسته نیست.

آیا در آزمون‌ها باید توکن واقعی داشته باشم؟

خیر. یک توکن آزمایشی غیرخالی تنظیم کنید و Bale::fake() را پیش از اجرای ارتباط با بله فراخوانی کنید. برای بررسی ارسال‌ها از ابزارهای آزمون پکیج استفاده کنید.

نگه‌داری، منابع و مشارکت

این پروژه را سجاد ده‌شیری نگه‌داری می‌کند و یک پکیج مستقل با مجوز ام‌آی‌تی هست؛ محصول رسمی تیم بله یا لاراول نیست. بستهٔ آن در Packagist در دسترس است. قراردادهای بله از مستندات رسمی بازو گرفته می‌شوند و ورودی و خروجی واقعی پکیج در کد منبع قابل‌بررسی هست.

برای بررسی کیفیت، آزمون‌ها، اجرای آزمون‌های خودکار و تاریخچهٔ تغییرات در دسترس هستند. اجرای محلی آزمون‌ها در نسخهٔ دریافت‌شده از مخزن:

composer install
composer test

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