PHPackages                             balebot/balebot - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. balebot/balebot

ActiveLibrary[API Development](/categories/api)

balebot/balebot
===============

The most complete PHP SDK for Bale Messenger bots. Supports Laravel out of the box.

v1.0.0(today)00MITPHPPHP ^8.1

Since Jun 9Pushed todayCompare

[ Source](https://github.com/Mahdyaralipor/balebot)[ Packagist](https://packagist.org/packages/balebot/balebot)[ Docs](https://github.com/balebot/balebot)[ RSS](/packages/balebot-balebot/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

BaleBot PHP SDK
===============

[](#balebot-php-sdk)

 [![Latest Version](https://camo.githubusercontent.com/2545604a2e1e976042cd1b7cf2472fe6c701663dcde3a9e74b1d6d2d65bd58c6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f62616c65626f742f62616c65626f74)](https://packagist.org/packages/balebot/balebot) [![PHP Version](https://camo.githubusercontent.com/fda1b81c38f7648a581b7061de44724869847e04ac1997a5a9b545f7b3b0536f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f62616c65626f742f62616c65626f74)](https://packagist.org/packages/balebot/balebot) [![CI Status](https://github.com/balebot/balebot/workflows/CI/badge.svg)](https://github.com/balebot/balebot/actions) [![Coverage](https://camo.githubusercontent.com/56a7db1efeb6ce7e4acdb76c11abb0a28d2341a223c2b089b2edec9445f321cd/68747470733a2f2f636f6465636f762e696f2f67682f62616c65626f742f62616c65626f742f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/balebot/balebot) [![License](https://camo.githubusercontent.com/8c3fc7d098fbb3de4e3c02b15ae539ead1ced4c514aa13d15b5d5a534d8c1951/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f62616c65626f742f62616c65626f74)](LICENSE)

The most complete, type-safe PHP SDK for building [Bale Messenger](https://bale.ai) bots. Works as a standalone library or with Laravel.

---

Features
--------

[](#features)

- ✅ **Type-safe** — all API responses mapped to PHP 8.1+ readonly DTOs
- ✅ **Zero dependencies** — native cURL only; Guzzle optional
- ✅ **Laravel-first** — auto-discovery, Facade, Artisan commands, config
- ✅ **Flexible routing** — commands, messages, callbacks, fallback + middleware pipeline
- ✅ **Webhook & long polling** — auto-detected at runtime
- ✅ **PHP 8.1+** — readonly properties, named arguments, enums

---

Installation
------------

[](#installation)

```
composer require balebot/balebot
```

### Laravel

[](#laravel)

Publish the config:

```
php artisan vendor:publish --tag=balebot-config
```

Add to `.env`:

```
BALE_BOT_TOKEN=your-token-here
```

---

Standalone Usage
----------------

[](#standalone-usage)

```
use BaleBot\Core\Bot;
use BaleBot\Keyboard\InlineKeyboardMarkup;
use BaleBot\Keyboard\InlineKeyboardButton;

$bot = new Bot(token: 'your-token');

$bot->onCommand('start', function ($update, $bot) {
    $keyboard = (new InlineKeyboardMarkup())
        ->row(
            InlineKeyboardButton::callback('خرید 🛒', 'action:buy'),
            InlineKeyboardButton::callback('راهنما ❓', 'action:help'),
        );

    $bot->sendMessage(
        $update->getChatId(),
        'به ربات خوش آمدید!',
        ['reply_markup' => $keyboard]
    );
});

$bot->onCallbackQuery(function ($update, $bot) {
    $bot->answerCallbackQuery($update->callbackQuery->id, ['text' => 'انجام شد ✓']);
});

$bot->run(); // auto-detects webhook or long polling
```

---

Laravel Usage
-------------

[](#laravel-usage)

```
// routes/web.php — nothing needed, route is auto-registered

// AppServiceProvider::boot()
use BaleBot\Laravel\Facades\Bale;
use BaleBot\Keyboard\ReplyKeyboardMarkup;
use BaleBot\Keyboard\ReplyKeyboardButton;

Bale::onCommand('start', function ($update, $bot) {
    $keyboard = (new ReplyKeyboardMarkup())
        ->row(
            ReplyKeyboardButton::make('گزینه ۱'),
            ReplyKeyboardButton::make('گزینه ۲'),
        )
        ->resize();

    Bale::sendMessage(
        $update->getChatId(),
        'سلام! یک گزینه انتخاب کنید:',
        ['reply_markup' => $keyboard]
    );
});
```

### Artisan Commands

[](#artisan-commands)

```
# Register webhook
php artisan balebot:webhook:set

# Register with a custom URL
php artisan balebot:webhook:set https://yourdomain.com/balebot/webhook

# Remove webhook
php artisan balebot:webhook:delete

# Start long polling (local development)
php artisan balebot:poll
php artisan balebot:poll --timeout=60
```

---

Middleware
----------

[](#middleware)

```
use BaleBot\Contracts\MiddlewareInterface;
use BaleBot\Types\Update;
use BaleBot\Contracts\BotInterface;

class AuthMiddleware implements MiddlewareInterface
{
    public function process(Update $update, BotInterface $bot, callable $next): void
    {
        $allowedIds = [123456, 789012];

        if (!in_array($update->getChatId(), $allowedIds)) {
            $bot->sendMessage($update->getChatId(), '⛔ دسترسی ندارید.');
            return;
        }

        $next();
    }
}

$bot->use(new AuthMiddleware());
```

---

Keyboards
---------

[](#keyboards)

```
use BaleBot\Keyboard\ReplyKeyboardMarkup;
use BaleBot\Keyboard\ReplyKeyboardButton;
use BaleBot\Keyboard\InlineKeyboardMarkup;
use BaleBot\Keyboard\InlineKeyboardButton;
use BaleBot\Keyboard\ReplyKeyboardRemove;

// Reply keyboard
$reply = (new ReplyKeyboardMarkup())
    ->row(ReplyKeyboardButton::make('گزینه ۱'), ReplyKeyboardButton::make('گزینه ۲'))
    ->row(ReplyKeyboardButton::make('بازگشت ↩️'))
    ->resize()
    ->oneTime();

// Inline keyboard
$inline = (new InlineKeyboardMarkup())
    ->row(
        InlineKeyboardButton::callback('تأیید ✅', 'confirm'),
        InlineKeyboardButton::callback('لغو ❌', 'cancel'),
    )
    ->row(
        InlineKeyboardButton::url('وب‌سایت 🌐', 'https://example.com'),
    );

// Remove keyboard
$remove = new ReplyKeyboardRemove();
```

---

Type System
-----------

[](#type-system)

All API responses return strongly-typed objects:

```
$message = $bot->sendMessage($chatId, 'سلام');
$message->messageId; // int
$message->chat->id;  // int
$message->from->fullName(); // string

$update->message->text;
$update->callbackQuery->data;
$update->getChatId(); // works for all update types
```

---

Requirements
------------

[](#requirements)

- PHP 8.1+
- `ext-curl`
- `ext-json`

**Optional:**

- Laravel 10 / 11 for framework integration
- `guzzlehttp/guzzle ^7.0` as alternative HTTP client

---

Contributing
------------

[](#contributing)

Please read [CONTRIBUTING.md](CONTRIBUTING.md) and open issues or pull requests on GitHub.

License
-------

[](#license)

MIT — see [LICENSE](LICENSE).

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7316fbf66cdbdfa2eea2079578cf5edca69c6d050bec1e3384471bdb09288702?d=identicon)[Mahdyaralipor](/maintainers/Mahdyaralipor)

---

Top Contributors

[![Mahdyaralipor](https://avatars.githubusercontent.com/u/142358745?v=4)](https://github.com/Mahdyaralipor "Mahdyaralipor (1 commits)")

---

Tags

phplaravelsdkbotBalebale-messengerbalebottelegram-like

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/balebot-balebot/health.svg)

```
[![Health](https://phpackages.com/badges/balebot-balebot/health.svg)](https://phpackages.com/packages/balebot-balebot)
```

###  Alternatives

[edbizarro/laravel-facebook-ads

Facebook & Instagram Ads for Laravel 5.6+

13429.8k](/packages/edbizarro-laravel-facebook-ads)[octw/aramex

A Library to integrate with Aramex APIs

2926.2k](/packages/octw-aramex)[wxm/taobao-sdk

淘宝 SDK 封装, 调用简单、语义化增强。支持 Laravel/Lumen。

1710.5k](/packages/wxm-taobao-sdk)[wxm/pdd-sdk

拼多多 SDK 封装, 调用简单、语义化增强。支持 Laravel/Lumen。

154.8k](/packages/wxm-pdd-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)