Telegram Bot Essentials

Appearance

Getting Started ​

Requirements ​

Installing the core package ​

bash
composer require telegram-bot-essentials/essence

Publish config and translations, then migrate:

bash
php artisan tbe:install
php artisan migrate

Configure config/tbe-essence.php and the following .env values before initializing your first bot:

dotenv
MAIN_UNIQUE_ID=main
MAIN_TELEGRAM_BOT_TOKEN=123456:your-bot-token
MAIN_ADMIN_CHAT_ID=123456789
MAIN_CURRENCY=USD

Initialize your main bot and register the webhook with Telegram:

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

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 ran tbe:set-webhook. See Reference → Routes for the full route table.

Project layout ​

Handler classes live under app/Telegram/. Since v0.12.0 they are scanned and registered once per worker boot (in TelegramBotServiceProvider), not on every request — see Architecture → Handler Registration:

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

Package defaults (from Essence itself and any companion module) load from each package's own src/Telegram/ directory alongside your app classes.

Scaffold new handlers with the built-in generators (all prefixed tbe:make:; --admin puts the class under Admin/ and pre-fills $perm, default Member/):

bash
php artisan tbe:make:callback-query MyFeatureQuery --admin
php artisan tbe:make:state-answer MyFeatureAnswer
php artisan tbe:make:reply-key MyFeatureKey
php artisan tbe:make:feature MyFeatureFeature --admin
php artisan tbe:make:inline-query MyInlineQuery
php artisan tbe:make:command MyStartCommand

Pass --all (or -f/-c/-r/-s) to a generator to emit the sibling handler classes in one go.

Adding companion modules ​

Every module in this ecosystem is an independent Composer package that depends on Essence (and sometimes on each other — e.g. Billing, Gateway: Card/Zibal, Affiliates, and User Wallet all build on top of telegram-bot-essentials/billing and/or settings). Install only what you need:

bash
composer require telegram-bot-essentials/settings
composer require telegram-bot-essentials/billing
composer require telegram-bot-essentials/gateway-zibal
composer require telegram-bot-essentials/user-management
composer require telegram-bot-essentials/user-wallet
composer require telegram-bot-essentials/affiliates
composer require telegram-bot-essentials/announcements

See each module's page under Modules in the sidebar for its own migrations, config, and setup steps — most require php artisan migrate and some require publishing a config file.

Essence and every companion package are published on Packagist as telegram-bot-essentials/*, so composer require works with no extra repositories configuration.

Where to next ​

  • Architecture — how an update flows from webhook to handler
  • Extending — building your first CallbackQuery / StateAnswer / Feature
  • State & StateData — multi-step input flows
  • Testing — the shared Testbench base and faked Telegram calls
  • Reference — helpers, config, database schema, artisan commands