Appearance
Introduction
Telegram Bot Essentials (package name essence, namespace TelegramBotEssentials\Essence) is a Laravel package for building multi-tenant Telegram bots with a structured request-routing architecture. Instead of one giant update handler, incoming webhook updates are dispatched through typed buses: Commands, ReplyKeys, CallbackQueries, and StateAnswers.
It is the core of a small ecosystem of packages, all namespaced under TelegramBotEssentials\* and installed via Composer into a host Laravel application.
Why it exists
Telegram bots built directly on top of an SDK tend to accumulate one of two problems as they grow: a single sprawling switch statement over every possible update shape, or ad-hoc session state stored in whatever column happened to be convenient. Essence fixes both by giving every kind of incoming update (slash command, keyboard button, inline button, freeform text while a flow is active) its own bus and its own class-based handler, and by giving multi-step flows a real state machine (bot_users.state + StateData) instead of scattered flags.
Because each bot is a stancl/tenancy tenant, the same Laravel application can run many independent bots — each with its own admins, users, settings, and billing — without duplicating code per bot.
The Ecosystem
| Package | Composer name | Purpose |
|---|---|---|
| Essence (core) | telegram-bot-essentials/essence | Webhook routing, buses, state machine, multi-tenancy, access control |
| Settings | telegram-bot-essentials/settings | Per-bot key/value settings with typed accessors |
| Billing | telegram-bot-essentials/billing | Invoices, payments, and a gateway abstraction |
| Gateway: Card | telegram-bot-essentials/gateway-card | Manual card-to-card payment gateway for Billing |
| Gateway: Zibal | telegram-bot-essentials/gateway-zibal | Zibal payment gateway integration for Billing |
| User Management | telegram-bot-essentials/user-management | Admin user list, sortable/filterable columns |
| User Wallet | telegram-bot-essentials/user-wallet | Per-user balance/credit wallet, plugs into User Management as a sort |
| Affiliates | telegram-bot-essentials/affiliates | Referral tracking and commission payout via the wallet |
| Announcements | telegram-bot-essentials/announcements | Bulk broadcast to bot users with live progress and retraction |
Two standalone (non-Telegram) API clients complete the toolkit for bots that resell VPN/proxy services:
| Package | Composer name | Purpose |
|---|---|---|
| Marzban API | elyar/marzban-api | PHP client for the Marzban panel API |
| Rebecca API | elyar/rebecca-api | PHP client for the Rebecca panel API |
All companion packages depend on Essence and register themselves into its buses and event system from their own service providers — see Extending and Events & Listeners.
Where to go next
- New to the framework? Start with Getting Started.
- Building a feature? Read Architecture then Extending.
- Building a multi-step input flow? Read State & StateData.
- Looking for a specific helper, config key, or artisan command? See Reference.