README

🤖 Bale Bot PHP SDK

The modern, feature-rich, and unofficial PHP SDK for the Bale Messenger Bot API.

Features • Installation • Laravel Setup • Quickstart • Usage Examples • API Reference • Testing • License

✨ Key Features

⚡ Complete API Coverage — Full support for all official endpoints from docs.bale.ai (Messages, Media, Chats, Webhooks, Payments, Commands, Stickers).
🚀 Laravel 10, 11, 12 & 13 Ready — Auto-discovered Service Provider, Facade (Bale::), and config publishing.
🤖 Multi-Bot Management — Seamlessly manage and toggle between multiple bot instances in a single application.
🎯 Webhook & Long Polling — Simple webhook handling in controllers and CLI polling with event dispatching.
💳 Bale Payments — Create invoice links, send invoices, handle pre_checkout_query, and inquire transaction statuses.
💬 Interactive Keyboards & Mini-Apps — Support for Inline Keyboards, Reply Keyboards, Web Apps (WebAppData, WebAppInfo), and Copy Text buttons.
🔔 Event Dispatcher — Built-in event system powered by Illuminate\Events for clean decoupled update handling.
🛡️ Modern & Secure — Built for PHP 8.2+, strictly typed, fully covered by automated PHPUnit tests.

📋 Requirements

Requirement	Minimum Version
PHP	`>= 8.2`
Laravel (optional)	`^10.0 \| ^11.0 \| ^12.0 \| ^13.0`
Required PHP Extensions	`ext-json`, `ext-curl`, `ext-mbstring`

📦 Installation

Install the package via Composer:

composer require erfanvahabpour/bale-bot-sdk

🚀 Laravel Integration

1. Publish Configuration

The package automatically registers its Service Provider and Bale Facade. Publish the configuration file:

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

This creates config/bale.php.

2. Configure Environment Variables

Add your bot token to your .env file:

BALE_BOT_TOKEN=your_bot_token_here

3. Multi-Bot Configuration (Optional)

Configure multiple bots in config/bale.php:

return [
    'default' => env('BALE_BOT_NAME', 'main_bot'),

    'bots' => [
        'main_bot' => [
            'token' => env('BALE_BOT_TOKEN'),
        ],
        'support_bot' => [
            'token' => env('BALE_SUPPORT_BOT_TOKEN'),
        ],
    ],
];

🏁 Quick Start

In Standalone PHP

use EFive\Bale\Api;

$bale = new Api('YOUR_BOT_TOKEN');

// Test authentication
$botUser = $bale->getMe();
echo "Connected as @{$botUser->username} (ID: {$botUser->id})";

// Send a message
$bale->sendMessage([
    'chat_id' => '123456789',
    'text'    => 'Hello from Bale Bot PHP SDK! 🚀',
]);

In Laravel

use EFive\Bale\Laravel\Facades\Bale;

// Uses default bot from config/bale.php
Bale::sendMessage([
    'chat_id' => '123456789',
    'text'    => 'Hello from Laravel! 🎉',
]);

// Or target a specific configured bot:
Bale::bot('support_bot')->sendMessage([
    'chat_id' => '123456789',
    'text'    => 'Support message',
]);

💡 Usage Examples

1. Sending Messages with Inline Keyboards

use EFive\Bale\Laravel\Facades\Bale;

$replyMarkup = [
    'inline_keyboard' => [
        [
            ['text' => '🌐 Open Website', 'url' => 'https://bale.ai'],
            ['text' => '👍 Like', 'callback_data' => 'action_like'],
        ],
        [
            ['text' => '🚀 Launch Mini-App', 'web_app' => ['url' => 'https://app.example.com']],
        ],
    ],
];

Bale::sendMessage([
    'chat_id'      => '123456789',
    'text'         => 'Choose an option below:',
    'reply_markup' => $replyMarkup,
]);

2. Sending Photos & Media Files

Upload local files, stream resources, or send existing file_ids:

use EFive\Bale\FileUpload\InputFile;
use EFive\Bale\Laravel\Facades\Bale;

// Upload local image
Bale::sendPhoto([
    'chat_id' => '123456789',
    'photo'   => InputFile::file('/path/to/image.png'),
    'caption' => 'Check out this photo! 📸',
]);

// Send document from raw string content on the fly
Bale::sendDocument([
    'chat_id'  => '123456789',
    'document' => InputFile::createFromContents('Invoice #10023...', 'invoice.txt'),
    'caption'  => 'Your invoice document',
]);

// Send Chat Action (typing indicator)
Bale::sendChatAction([
    'chat_id' => '123456789',
    'action'  => 'upload_photo',
]);

3. Handling Webhooks in Laravel

Define a route in routes/api.php or routes/web.php:

use Illuminate\Http\Request;
use EFive\Bale\Laravel\Facades\Bale;

Route::post('/bale/webhook', function (Request $request) {
    $update = Bale::getWebhookUpdate();

    if ($update->isType('message')) {
        $message = $update->message;
        $chatId  = $message->chat->id;
        $text    = $message->text;

        if ($text === '/start') {
            Bale::sendMessage([
                'chat_id' => $chatId,
                'text'    => "Welcome, {$message->from->first_name}!",
            ]);
        }
    } elseif ($update->isType('callback_query')) {
        $callback = $update->callbackQuery;

        Bale::answerCallbackQuery([
            'callback_query_id' => $callback->id,
            'text'              => 'Action received!',
            'show_alert'        => false,
        ]);
    }

    return response()->json(['ok' => true]);
});

4. Setting & Deleting Webhook

// Register webhook URL
Bale::setWebhook([
    'url' => 'https://yourdomain.com/api/bale/webhook',
]);

// Delete webhook
Bale::deleteWebhook();

// Get current webhook info
$info = Bale::getWebhookInfo();
echo $info->url;

5. Managing Chat Members & Admins

// Get list of chat administrators
$admins = Bale::getChatAdministrators(['chat_id' => '-100123456789']);
foreach ($admins as $admin) {
    echo "{$admin->user->first_name} ({$admin->status})\n";
}

// Get specific member info
$member = Bale::getChatMember([
    'chat_id' => '-100123456789',
    'user_id' => 123456,
]);

// Promote member
Bale::promoteChatMember([
    'chat_id'             => '-100123456789',
    'user_id'             => 123456,
    'can_delete_messages' => true,
    'can_pin_messages'    => true,
]);

// Ban and Unban
Bale::banChatMember(['chat_id' => '-100123456789', 'user_id' => 123456]);
Bale::unbanChatMember(['chat_id' => '-100123456789', 'user_id' => 123456]);

6. Payments & Invoices

// 1. Send an invoice in chat
Bale::sendInvoice([
    'chat_id'        => '123456789',
    'title'          => 'Premium Subscription',
    'description'    => '1-month access to premium content',
    'payload'        => 'sub_monthly_user_123',
    'provider_token' => 'YOUR_PROVIDER_TOKEN',
    'prices'         => [
        ['label' => 'Subtotal', 'amount' => 500000],
    ],
]);

// 2. Generate a shareable invoice payment link
$invoiceUrl = Bale::createInvoiceLink([
    'title'          => 'Product Name',
    'description'    => 'Product Description',
    'payload'        => 'order_9988',
    'provider_token' => 'YOUR_PROVIDER_TOKEN',
    'prices'         => [
        ['label' => 'Price', 'amount' => 250000],
    ],
]);

// 3. Answer Pre-Checkout Query (in webhook)
if ($update->isType('pre_checkout_query')) {
    Bale::answerPreCheckoutQuery([
        'pre_checkout_query_id' => $update->pre_checkout_query->id,
        'ok'                    => true,
    ]);
}

// 4. Inquire transaction status
$transaction = Bale::inquireTransaction([
    'payment_charge_id' => 'chg_123456',
]);
echo "Status: {$transaction->status}";

📚 API Method Reference

All methods return strongly-typed BaseObject models or booleans:

Category	Available Methods
Bot & Updates	`getMe`, `getUpdates`, `setWebhook`, `deleteWebhook`, `removeWebhook`, `getWebhookInfo`, `getWebhookUpdate`
Messaging	`sendMessage`, `forwardMessage`, `copyMessage`, `editMessageText`, `editMessageCaption`, `editMessageReplyMarkup`, `deleteMessage`, `sendChatAction`
Media Uploads	`sendPhoto`, `sendAudio`, `sendDocument`, `sendVideo`, `sendAnimation`, `sendVoice`, `sendMediaGroup`, `getFile`, `downloadFile`
Chat Management	`getChat`, `getChatAdministrators`, `getChatMembersCount`, `getChatMember`, `banChatMember`, `unbanChatMember`, `promoteChatMember`, `leaveChat`, `setChatTitle`, `setChatDescription`, `setChatPhoto`, `deleteChatPhoto`, `pinChatMessage`, `unpinChatMessage`, `unpinAllChatMessages`, `createChatInviteLink`, `revokeChatInviteLink`, `exportChatInviteLink`
Interactions	`answerCallbackQuery`, `askReview`, `sendContact`, `sendLocation`
Payments	`sendInvoice`, `createInvoiceLink`, `answerPreCheckoutQuery`, `inquireTransaction`
Commands	`setMyCommands`, `deleteMyCommands`, `getMyCommands`
Stickers	`sendSticker`, `uploadStickerFile`, `createNewStickerSet`, `addStickerToSet`

🧪 Testing

Run the test suite using PHPUnit:

composer test
# or
./vendor/bin/phpunit

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an Issue.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Ensure all tests pass (composer test)
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

💖 Funding & Support

If this SDK helps you build your bots, please consider supporting the project:

Email: info@efive.net
Website: efive.net
Donate: Aqayepardakht

📄 License & Disclaimer

License: Released under the BSD 4-Clause License.
Disclaimer: This project is an unofficial community library and is not officially affiliated with or endorsed by Bale.

erfanvahabpour / bale-bot-sdk

Maintainers

Package info

Fund package maintenance!

Statistics

Security