PHPackages                             phpsoftbox/telegram - 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. [Utility & Helpers](/categories/utility)
4. /
5. phpsoftbox/telegram

ActiveLibrary[Utility & Helpers](/categories/utility)

phpsoftbox/telegram
===================

Telegram bot builder for the PhpSoftBox framework

094PHP

Since Apr 30Pushed 3mo agoCompare

[ Source](https://github.com/phpsoftbox/telegram)[ Packagist](https://packagist.org/packages/phpsoftbox/telegram)[ RSS](/packages/phpsoftbox-telegram/feed)WikiDiscussions master Synced 4w ago

READMEChangelogDependenciesVersions (1)Used By (0)

Telegram
========

[](#telegram)

About
-----

[](#about)

`phpsoftbox/telegram` — компонент для построения Telegram-ботов: команды, обработчики, диалоги (Q&A) и веб-хук.

Ключевые возможности:

- подключение к Telegram API и работа с webhook;
- роутинг команд и сообщений по типу;
- диалоги с вопросами, отменой и сбором данных;
- flow engine для централизованного описания переходов и guard-условий;
- авторизация через Telegram Login Widget;
- очистка сообщений для «чистого экрана».

Quick Start
-----------

[](#quick-start)

Основная идея: `Bot` принимает update, сначала пытается продолжить активный диалог, затем отдает управление `UpdateRouter`.

```
use PhpSoftBox\Telegram\Api\TelegramClient;
use PhpSoftBox\Telegram\Bot\Bot;
use PhpSoftBox\Telegram\Conversation\ArrayConversationStore;
use PhpSoftBox\Telegram\Conversation\ConversationDefinition;
use PhpSoftBox\Telegram\Conversation\ConversationManager;
use PhpSoftBox\Telegram\Conversation\QuestionStep;
use PhpSoftBox\Telegram\Router\UpdateRouter;
use PhpSoftBox\Telegram\Webhook\WebhookHandler;

$client = new TelegramClient(
    token: $_ENV['TELEGRAM_BOT_TOKEN'],
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
);

$router = new UpdateRouter();
$router->command('start', static function ($update, $context): void {
    $context->sendMessage($update->chatId(), 'Привет!');
});

$store = new ArrayConversationStore();
$conversations = new ConversationManager($store, $client);
$conversations->register(new ConversationDefinition('workspace.create', [
    new QuestionStep('name', 'Название воркспейса?'),
    new QuestionStep('description', 'Описание воркспейса?'),
]));

$router->command('workspace', static function ($update, $context) use ($conversations): void {
    $conversations->start('workspace.create', $update);
});

$bot = new Bot($client, $router, $conversations);
$handler = new WebhookHandler($bot, $responseFactory, $streamFactory);

$response = $handler->handle($request);
```

Команды и обработчики
---------------------

[](#команды-и-обработчики)

Команды и хендлеры регистрируются в `UpdateRouter`. Можно слушать текстовые сообщения, типы сообщений и fallback.

```
use PhpSoftBox\Telegram\Update\MessageTypeEnum;

$router->command('start', fn ($update, $context) => ...);
$router->onText(fn ($update, $context) => ...);
$router->onCallbackData('trial:start', fn ($update, $context) => ...);
$router->onCallbackQuery(fn ($update, $context) => ...);
$router->onType(MessageTypeEnum::PHOTO, fn ($update, $context) => ...);
$router->fallback(fn ($update, $context) => ...);
```

Конфигурация бота
-----------------

[](#конфигурация-бота)

Если команд много, используйте `TelegramBotBuilder` и описывайте команды по файлам в `config/telegram` или через атрибуты.

```
use PhpSoftBox\Telegram\Builder\TelegramBotBuilder;

return static function (TelegramBotBuilder $bot): void {
    $bot->command('start', StartCommand::class);
    $bot->command('reset', ResetCommand::class);
};
```

### Несколько ботов

[](#несколько-ботов)

Можно держать несколько ботов, разделяя их по имени в конфиге (`auth`, `main`, `news`) и указывая `default`.

Диалоги (Q&A)
-----------------

[](#диалоги-qa)

Диалоги строятся из последовательности шагов. Шаг может парсить и валидировать ответ пользователя.

```
$definition = new ConversationDefinition('workspace.edit', [
    new QuestionStep('name', 'Новое название?'),
    new QuestionStep('description', 'Новое описание?'),
]);
$definition = $definition->withCancelKeywords(['/cancel', 'cancel']);

$conversations->register($definition);
$conversations->start('workspace.edit', $update);
```

Авторизация через Telegram
--------------------------

[](#авторизация-через-telegram)

Авторизация вынесена в отдельный пакет `phpsoftbox/telegram-auth`.

Файлы
-----

[](#файлы)

Если в update приходит `file_id` (фото, видео, документ), файл можно скачать через `downloadFile`:

```
$fileId = $update->message()?->value();
if ($fileId !== null) {
    $client->downloadFile($fileId, __DIR__ . '/storage/file.bin');
}
```

Оглавление
----------

[](#оглавление)

- [Документация](docs/index.md)
- [CLI (long polling)](docs/07-cli.md)
- [Flow Engine](docs/08-flow.md)
- [Scenario Builder](docs/09-scenario-builder.md)

Дополнения
----------

[](#дополнения)

- `phpsoftbox/telegram-auth` — авторизация через Telegram Login Widget.
- `phpsoftbox/telegram-mongo` — MongoDB-хранилище диалогов.

###  Health Score

21

—

LowBetter than 17% of packages

Maintenance54

Moderate activity, may be stable

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/0279d150240c97d210034878b0467462246dc14d29b5618157ff6a8be49a50e3?d=identicon)[inspector-who](/maintainers/inspector-who)

---

Top Contributors

[![inspector-who](https://avatars.githubusercontent.com/u/6973963?v=4)](https://github.com/inspector-who "inspector-who (1 commits)")

### Embed Badge

![Health badge](/badges/phpsoftbox-telegram/health.svg)

```
[![Health](https://phpackages.com/badges/phpsoftbox-telegram/health.svg)](https://phpackages.com/packages/phpsoftbox-telegram)
```

###  Alternatives

[components/jqueryui

jQuery UI is a curated set of user interface interactions, effects, widgets, and themes built on top of the jQuery JavaScript Library. Whether you're building highly interactive web applications or you just need to add a date picker to a form control, jQuery UI is the perfect choice.

1775.9M61](/packages/components-jqueryui)

PHPackages © 2026

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