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 ​

The webhook controller auto-loads handler classes from app/Telegram/ on every request:

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

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:

bash
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

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.

Private packages

These packages are distributed via VCS (GitHub) Composer repositories rather than Packagist. Add a matching repositories entry for each one to your composer.json:

json
{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/telegram-bot-essentials/essence"
        }
    ]
}

Repeat the entry (with the matching URL) for every companion package you install.

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
  • Reference — helpers, config, database schema, artisan commands