PHPackages                             laravel-bale-bot/laravel-bale - 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. laravel-bale-bot/laravel-bale

ActiveLibrary[API Development](/categories/api)

laravel-bale-bot/laravel-bale
=============================

Laravel package to integrate with Bale messenger (bot API)

v1.1.0(8mo ago)038MITPHPPHP ^8.2

Since Oct 15Pushed 8mo agoCompare

[ Source](https://github.com/laravel-bale-bot/laravel-bale)[ Packagist](https://packagist.org/packages/laravel-bale-bot/laravel-bale)[ Docs](https://github.com/laravel-bale-bot/laravel-bale)[ RSS](/packages/laravel-bale-bot-laravel-bale/feed)WikiDiscussions main Synced 2d ago

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

Laravel Bale Bot Package 🤖
==========================

[](#laravel-bale-bot-package-)

A robust and developer-friendly Laravel package for building and managing bots on **[Bale Messenger](https://bale.ai)**.
This package provides a **modern**, **extendable**, and **dynamic** integration layer with the Bale Bot API, making it easy to send messages, handle updates, manage callbacks, and automate complex bot workflows — all within your Laravel application.

---

📑 Table of Contents
-------------------

[](#-table-of-contents)

- [Features](#-features)
- [Requirements](#-requirements)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Usage](#-usage)
    - [Sending Messages](#-sending-messages)
    - [Sending Files and Media](#-sending-photos-files-and-other-media)
    - [Handling Incoming Messages](#-replying-to-incoming-messages)
    - [Handling Commands](#-handling-commands)
    - [Inline Keyboards](#-inline-keyboard-and-buttons)
    - [Polling Mode](#-polling-alternative-to-webhook)
    - [Working with Queues](#-working-with-queues)
    - [Advanced Example](#-advanced-example-auto-responder-bot)
    - [Raw API Access](#-accessing-raw-api-methods)
    - [Custom Webhook Controller](#-custom-webhook-controller-optional)
- [Summary](#-summary)
- [Contributing](#-contributing)
- [License](#-license)

---

✨ Features
----------

[](#-features)

- 🧠 Clean and expressive API for Bale Bot
- ⚙️ Works seamlessly with **Laravel 10+**
- 🌐 Supports both **Webhook** and **Long Polling**
- ⚡ Asynchronous message handling via Laravel queues
- 🔔 Built-in event system for updates, callbacks, and media
- 🧩 Extensible architecture for advanced bot customization
- 📦 Follows PSR-12 and SOLID design principles
- 🔒 Secure and production-ready

---

🧰 Requirements
--------------

[](#-requirements)

- PHP 8.1 or higher
- Laravel 10 or newer
- cURL or Guzzle HTTP client
- Bale Bot Token (from [Bale BotFather](https://docs.bale.ai/#/))

---

⚙️ Installation
---------------

[](#️-installation)

Install the package via Composer:

```
composer require laravel-bale-bot/laravel-bale
```

Then publish the configuration file:

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

This will create a `config/bale.php` file in your project.

---

🧩 Configuration
---------------

[](#-configuration)

Edit the configuration file `config/bale.php`:

```
return [
    'token' => env('BALE_BOT_TOKEN', ''),
    'webhook_url' => env('BALE_WEBHOOK_URL', ''),
    'use_queue' => env('BALE_USE_QUEUE', true),
    'poll_interval' => env('BALE_POLL_INTERVAL', 2),
];
```

Add the following lines to your `.env` file:

```
BALE_BOT_TOKEN=your-bale-bot-token-here
BALE_WEBHOOK_URL=https://yourdomain.com/bale/webhook
BALE_USE_QUEUE=true
```

Register your webhook with:

```
php artisan bale:set-webhook
```

To remove the webhook and use polling mode instead:

```
php artisan bale:delete-webhook
```

---

💡 Usage
-------

[](#-usage)

The Laravel Bale Bot package aims to provide a **fluent and flexible** API for building bots.
You can use it via **dependency injection**, the **Bale facade**, or directly with the **service container**.

---

### 📨 Sending Messages

[](#-sending-messages)

You can send text messages via the injected client or facade.

**Using dependency injection:**

```
use LaravelBaleBot\LaravelBale\LaravelBale\Contracts\BaleClientInterface;

class NotificationService
{
    public function __construct(protected BaleClientInterface $bale) {}

    public function notify($chatId, $text)
    {
        $this->bale->sendMessage($chatId, $text);
    }
}
```

**Using the facade:**

```
use LaravelBaleBot\LaravelBale\LaravelBale\Facades\Bale;

Bale::sendMessage(12345678, 'Hello Bale!');
```

**With optional parameters:**

```
Bale::sendMessage(12345678, 'Click below 👇', [
    'reply_markup' => [
        'keyboard' => [['Yes', 'No']],
        'resize_keyboard' => true,
        'one_time_keyboard' => true,
    ]
]);
```

---

### 📎 Sending Photos, Files, and Other Media

[](#-sending-photos-files-and-other-media)

Send photos, documents, or voice messages easily:

```
Bale::sendPhoto($chatId, storage_path('app/public/welcome.jpg'), 'Welcome!');
Bale::sendDocument($chatId, storage_path('app/docs/guide.pdf'), 'User Guide');
Bale::sendVoice($chatId, storage_path('app/audio/hello.ogg'), 'Voice message');
```

The package handles file uploads and Bale API formatting automatically.

---

### 🔁 Replying to Incoming Messages

[](#-replying-to-incoming-messages)

Incoming messages trigger a `MessageReceived` event.

Example listener:

```
use LaravelBaleBot\LaravelBale\LaravelBale\Events\MessageReceived;
use LaravelBaleBot\LaravelBale\LaravelBale\Facades\Bale;

class RespondToUser
{
    public function handle(MessageReceived $event)
    {
        $chatId = $event->message['chat']['id'];
        $text = strtolower($event->message['text'] ?? '');

        match ($text) {
            'hello' => Bale::sendMessage($chatId, 'Hi there 👋'),
            'help' => Bale::sendMessage($chatId, 'How can I help you today?'),
            default => Bale::sendMessage($chatId, 'Sorry, I did not understand that.')
        };
    }
}
```

---

### ⚙️ Handling Commands

[](#️-handling-commands)

For handling commands like `/start`, `/about`, etc.:

```
if (str_starts_with($text, '/start')) {
    Bale::sendMessage($chatId, "Welcome to the Bale Bot 🎉");
} elseif (str_starts_with($text, '/about')) {
    Bale::sendMessage($chatId, "This bot is powered by Laravel Bale.");
}
```

You can later register these commands in a `CommandRouter` for a cleaner structure.

---

### 🧩 Inline Keyboard and Buttons

[](#-inline-keyboard-and-buttons)

Create interactive inline keyboards:

```
$keyboard = [
    'inline_keyboard' => [
        [
            ['text' => 'Visit Website 🌐', 'url' => 'https://example.com'],
            ['text' => 'Support 💬', 'callback_data' => 'support']
        ]
    ]
];

Bale::sendMessage($chatId, 'Choose an option:', ['reply_markup' => $keyboard]);
```

**Handle callbacks:**

```
use LaravelBaleBot\LaravelBale\LaravelBale\Events\CallbackQueryReceived;

class HandleCallback
{
    public function handle(CallbackQueryReceived $event)
    {
        $data = $event->callbackQuery['data'];
        $chatId = $event->callbackQuery['message']['chat']['id'];

        if ($data === 'support') {
            Bale::sendMessage($chatId, 'Please describe your issue. Our support team will contact you soon.');
        }
    }
}
```

---

### 🔄 Polling (Alternative to Webhook)

[](#-polling-alternative-to-webhook)

If you don’t want to use webhooks, use polling:

```
php artisan bale:poll-updates
```

You can change the polling interval in `config/bale.php`.

---

### 🧵 Working with Queues

[](#-working-with-queues)

Each update is automatically dispatched to a queued job (`HandleUpdateJob`).
Run the queue worker:

```
php artisan queue:work
```

You can modify the queue settings in your `.env` or `config/queue.php`.

---

### 🧠 Advanced Example: Auto Responder Bot

[](#-advanced-example-auto-responder-bot)

A simple auto-responder bot example:

```
namespace App\Listeners;

use LaravelBaleBot\LaravelBale\LaravelBale\Events\MessageReceived;
use LaravelBaleBot\LaravelBale\LaravelBale\Facades\Bale;

class AutoResponder
{
    public function handle(MessageReceived $event)
    {
        $chatId = $event->message['chat']['id'];
        $text = trim(strtolower($event->message['text'] ?? ''));

        $responses = [
            'hi' => 'Hello! 👋',
            'how are you' => 'I’m doing great, thanks for asking!',
            'bye' => 'Goodbye! See you soon 👋',
        ];

        $reply = $responses[$text] ?? "I didn’t quite catch that. Type 'help' for available commands.";

        Bale::sendMessage($chatId, $reply);
    }
}
```

---

### 🧰 Accessing Raw API Methods

[](#-accessing-raw-api-methods)

For full API control, use the `api()` method:

```
$response = Bale::api('getChat', ['chat_id' => 12345678]);
```

Or through the injected HTTP client:

```
$bale->call('getChat', ['chat_id' => 12345678]);
```

---

### 🪄 Custom Webhook Controller (Optional)

[](#-custom-webhook-controller-optional)

Create your own webhook controller if you prefer direct handling:

```
use LaravelBaleBot\LaravelBale\LaravelBale\Http\Controllers\BaleWebhookController;

class CustomWebhookController extends BaleWebhookController
{
    public function handleUpdate(array $update)
    {
        Log::info('Received update:', $update);
        return response()->json(['ok' => true]);
    }
}
```

And register it in `routes/web.php`:

```
Route::post('/bale/custom-webhook', [CustomWebhookController::class, 'handle']);
```

---

📋 Summary
---------

[](#-summary)

ActionExampleSend text`Bale::sendMessage($chatId, 'Hello')`Send photo`Bale::sendPhoto($chatId, $path, 'Caption')`Send document`Bale::sendDocument($chatId, $filePath)`Handle messages`MessageReceived` eventHandle callbacks`CallbackQueryReceived` eventSet webhook`php artisan bale:set-webhook`Poll updates`php artisan bale:poll-updates`Use queue`php artisan queue:work`---

🤝 Contributing
--------------

[](#-contributing)

We welcome all contributions!
To contribute, please:

1. Fork the repository
2. Create a new branch for your feature or bugfix
3. Write clean, tested, and well-documented code
4. Submit a Pull Request

Make sure your code follows **PSR-12**, uses **type hints**, and includes **unit tests** when possible.

---

📜 License
---------

[](#-license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

---

**Developed with ❤️ for the Laravel Community — making bot development faster, cleaner, and more enjoyable.**

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance59

Moderate activity, may be stable

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

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

Every ~31 days

Total

2

Last Release

269d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b8292caa8b7d6c67ce92c52528963ec05e49422cb23613e47b78838921779c24?d=identicon)[khody2012](/maintainers/khody2012)

---

Top Contributors

[![khody2012](https://avatars.githubusercontent.com/u/49361472?v=4)](https://github.com/khody2012 "khody2012 (8 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/laravel-bale-bot-laravel-bale/health.svg)

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

###  Alternatives

[defstudio/telegraph

A laravel facade to interact with Telegram Bots

818355.4k3](/packages/defstudio-telegraph)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5226.7k](/packages/simplestats-io-laravel-client)

PHPackages © 2026

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