Telegram Bot Essentials (Essence)

A Laravel package for running many Telegram bots from one codebase, each bot its own tenant. Instead of one giant update handler per bot, incoming webhook updates are dispatched through typed buses - Commands, ReplyKeys, CallbackQueries, and StateAnswers - so a multi-tenant, multi-locale bot platform stays organized as it grows past a handful of features.

Requirements

• PHP ^8.3
• Laravel ^12 or ^13
• irazasyed/telegram-bot-sdk ^3.15
• stancl/tenancy ^3.9 (each bot is a tenant)

Installation

composer require telegram-bot-essentials/essence

Publish config and translations:

php artisan tbe:install
php artisan migrate

Initialize your main bot and set the webhook:

php artisan tbe:singlebot:init
php artisan tbe:set-webhook

Configure config/tbe-essence.php and .env values (MAIN_TELEGRAM_BOT_TOKEN, MAIN_UNIQUE_ID, MAIN_ADMIN_CHAT_ID, etc.) before running init.

Webhook URL

Each bot receives updates at:

POST /api/{bot_unique_id}/telegram/bot/webhook

Authentication uses the Telegram secret_token header, verified against the hashed token stored on the bots table when you run tbe:set-webhook.

Core Concepts

Concept	Trigger	Purpose
Commands	/start, /help, …	Slash-command handlers
ReplyKeys	Keyboard button text	Main menu and navigation
CallbackQueries	Inline button presses	Menus, actions, starting input flows
StateAnswers	Text/media while user has active state	Multi-step input, form wizards
Features	Called from queries/answers	Build TelegramResponse messages
MessageMeta	Associated with messages	Lock, revert, and update bot messages
StateData	Referenced by ID	JSON payload storage for wizards and deeplinks

Project Layout (in your Laravel app)

app/Telegram/
├── CallbackQueries/
│   ├── Admin/
│   └── Member/
├── StateAnswers/
│   ├── Admin/
│   └── Member/
├── ReplyKeys/
│   ├── Admin/
│   └── Member/
├── Features/
│   ├── Admin/
│   └── Member/
└── Commands/

Handlers are discovered from app/Telegram/** once per process/worker at boot, after every companion package has registered its own - so your app's handlers always win a naming collision. Package defaults are loaded from vendor/telegram-bot-essentials/essence/src/Telegram/.

Documentation

The full documentation site — the single source of truth — is maintained separately and being published. It covers:

• Architecture — webhook flow, buses, encoding formats
• State & StateData — bot_users.state vs the state_data table
• Extending — building CallbackQueries, StateAnswers, Features
• Commands — CommandBus, aliases, programmatic routing
• Events & Listeners — the bot event bus
• Reference — helpers, config, database, artisan commands

Artisan Generators

php artisan make:callback-query Admin/MyFeatureQuery
php artisan make:state-answer Member/MyFeatureAnswer
php artisan make:reply-key Member/MyFeatureKey
php artisan make:feature Admin/MyFeatureFeature
php artisan make:command MyStartCommand

Testing

Extend TelegramBotEssentials\Essence\Testing\TestCase (a Testbench base essence ships in src/) instead of wiring up Testbench yourself - every companion package already depends on essence, so no extra dependency is needed:

use TelegramBotEssentials\Essence\Testing\TestCase;
use Illuminate\Foundation\Testing\RefreshDatabase;

uses(TestCase::class, RefreshDatabase::class);

it('replies when the button is pressed', function () {
    $bot = $this->makeBot();

    $this->postWebhookUpdate($bot, $this->makeMessageUpdate('Main Menu 🔰'))
        ->assertOk();

    $this->assertTelegramSent(fn ($request) => str_contains($request['text'], 'Main Menu loaded'));
});

postWebhookUpdate() sends a real request through routing, TelegramBotAuthentication, and the controller - not a hand-wired shortcut. Outbound Telegram API calls are faked automatically (Http::fake() in setUp()): LaravelHttpClient, essence's default http_client_handler, routes every SDK call through Illuminate\Support\Facades\Http, so no bespoke SDK mocking is needed.

Related Packages

Essence is the core framework. Optional companion packages, all on Packagist under telegram-bot-essentials/*, extend it:

• telegram-bot-essentials/settings — per-bot typed key/value settings
• telegram-bot-essentials/billing — invoices, payments, gateway registry
• telegram-bot-essentials/gateway-card — manual card-to-card gateway for Billing
• telegram-bot-essentials/gateway-zibal — Zibal gateway for Billing
• telegram-bot-essentials/user-wallet — per-user balance/credit wallet
• telegram-bot-essentials/user-management — admin user list, sortable/filterable
• telegram-bot-essentials/affiliates — referral tracking and wallet payouts
• telegram-bot-essentials/announcements — bulk broadcast with live progress

Register their CallbackQueries and StateAnswers in each package's service provider via callbackQueryBus() and stateAnswerBus().

Contributing

See CONTRIBUTING.md for local setup, the test/lint/analyse commands CI runs, and commit conventions.

License

MIT