PHPackages                             koot-labs/telegram-bot-dialogs - 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. [API Development](/categories/api)
4. /
5. koot-labs/telegram-bot-dialogs

ActiveLibrary[API Development](/categories/api)

koot-labs/telegram-bot-dialogs
==============================

Telegram Bot API PHP SDK extension that allows to implement dialogs in bots

1.2.2(9mo ago)142.0k↓43.2%5[1 PRs](https://github.com/koot-labs/telegram-bot-dialogs/pulls)MITPHPPHP >=8.1CI passing

Since Jun 20Pushed 4mo ago1 watchersCompare

[ Source](https://github.com/koot-labs/telegram-bot-dialogs)[ Packagist](https://packagist.org/packages/koot-labs/telegram-bot-dialogs)[ Docs](https://github.com/koot-labs/telegram-bot-dialogs)[ RSS](/packages/koot-labs-telegram-bot-dialogs/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (9)Versions (42)Used By (0)

[![CI](https://github.com/koot-labs/telegram-bot-dialogs/actions/workflows/ci.yml/badge.svg)](https://github.com/koot-labs/telegram-bot-dialogs/actions/workflows/ci.yml)[![Backward compatibility check](https://github.com/koot-labs/telegram-bot-dialogs/actions/workflows/backward-compatibility-check.yml/badge.svg)](https://github.com/koot-labs/telegram-bot-dialogs/actions/workflows/backward-compatibility-check.yml)[![Type coverage](https://camo.githubusercontent.com/93230906ce8cbd7806841033911970d7428f47b286b5278ea87fe0c4aba5a6e8/68747470733a2f2f73686570686572642e6465762f6769746875622f6b6f6f742d6c6162732f74656c656772616d2d626f742d6469616c6f67732f636f7665726167652e737667)](https://shepherd.dev/github/koot-labs/telegram-bot-dialogs)[![Psalm level](https://camo.githubusercontent.com/a399fdfd05cf361520b4464b0c399b919174647c080135e115df9540d08a1605/68747470733a2f2f73686570686572642e6465762f6769746875622f6b6f6f742d6c6162732f74656c656772616d2d626f742d6469616c6f67732f6c6576656c2e737667)](https://shepherd.dev/github/koot-labs/telegram-bot-dialogs)[![codecov](https://camo.githubusercontent.com/ab52c0e29966a557d50a87dcf7a1dcb15815fd4a6d9bee95cfa537d02a9e2b0e/68747470733a2f2f636f6465636f762e696f2f6769746875622f6b6f6f742d6c6162732f74656c656772616d2d626f742d6469616c6f67732f67726170682f62616467652e7376673f746f6b656e3d31334135415255594451)](https://codecov.io/github/koot-labs/telegram-bot-dialogs)

[![Dialogs](https://user-images.githubusercontent.com/5278175/176997422-79e5c4c1-ff43-438e-b30e-651bb8e17bcf.png)](https://user-images.githubusercontent.com/5278175/176997422-79e5c4c1-ff43-438e-b30e-651bb8e17bcf.png)

Dialogs Plugin for Telegram Bot API PHP SDK
===========================================

[](#dialogs-plugin-for-telegram-bot-api-php-sdk)

A powerful extension for [Telegram Bot API PHP SDK](https://github.com/irazasyed/telegram-bot-sdk) v3.1+ that enables dialog-based interactions in your Telegram bots.

Table of Contents
-----------------

[](#table-of-contents)

- [About](#about)
- [Features](#features)
- [Installation](#installation)
    - [Laravel Integration](#laravel-integration)
    - [Framework-agnostic Usage](#framework-agnostic-usage)
- [Basic Usage](#basic-usage)
    - [Creating a Dialog](#creating-a-dialog)
    - [Setting up Commands](#setting-up-commands)
    - [Controller Setup](#controller-setup)
- [Advanced Usage](#advanced-usage)
    - [Dialog Class API](#dialog-class-api)
    - [DialogManager API](#dialogmanager-api)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)
- [Roadmap](#roadmap)

About
-----

[](#about)

This package is a maintained fork of the original Telegram Bot Dialogs package, updated to support Telegram Bot API PHP SDK v3, PHP 8+, and modern Laravel features. Our focus is on stability, developer experience, and code readability.

### Why This Fork?

[](#why-this-fork)

The Original package [is not maintained anymore](https://github.com/koot-labs/telegram-bot-dialogs/commit/e9c7667e56e419a7053125b40c473ce4b8d7f9c8) and does not support Telegram Bot API PHP SDK v3. The goal of the fork is to maintain the package compatible with the latest [Telegram Bot API PHP SDK](https://github.com/irazasyed/telegram-bot-sdk), PHP 8+ and Laravel features, focus on stability, better DX and readability.

Features
--------

[](#features)

- Framework-agnostic design with enhanced Laravel support
- Dialog-based conversation flow management
- State persistence between messages
- Flexible step navigation
- Support for multiple active dialogs

Scope of the package
--------------------

[](#scope-of-the-package)

Any bot app basically listens to Updates from Telegram API (using your webhook endpoint or by pulling these updates on any trigger, like cron) and sends messages back.

This package helps to implement a dialog mode for your bot: for a given Update, check whether the Update belongs to an already activated Dialog and if there is, run the next step of the Dialog.

This package doesn't solve the task to activate Dialogs for a given Update—you need to implement this logic in your app. Different apps may have different strategies to activate Dialogs (e.g. by commands, by message content, by message type, by user\_id, etc.). The package provides an API to activate Dialogs and run the next step for the active Dialog.

Installation
------------

[](#installation)

Install via Composer:

```
composer require koot-labs/telegram-bot-dialogs
```

### Laravel Integration

[](#laravel-integration)

1. The package automatically registers `\KootLabs\TelegramBotDialogs\Laravel\DialogsServiceProvider`
2. Publish the configuration:

```
php artisan vendor:publish --tag="telegram-config"
```

This creates `config/telegramdialogs.php` with these environment variables:

- `TELEGRAM_DIALOGS_CACHE_DRIVER` (default: `database`)
- `TELEGRAM_DIALOGS_CACHE_PREFIX` (default: `tg_dialog_`)

### Framework-agnostic Usage

[](#framework-agnostic-usage)

For non-Laravel applications, see our [framework-agnostic guide](./docs/using-without-framework.md).

Basic Usage
-----------

[](#basic-usage)

### 1. Creating a Dialog

[](#1-creating-a-dialog)

Create a dialog class extending `Dialog`:

```
use KootLabs\TelegramBotDialogs\Dialog;
use Telegram\Bot\Objects\Update;

final class HelloDialog extends Dialog
{
    /** @var list List of method to execute. The order defines the sequence */
    protected array $steps = ['sayHello', 'sayOk'];

    public function sayHello(Update $update): void
    {
        $this->bot->sendMessage([
            'chat_id' => $this->getChatId(),
            'text' => 'Hello! How are you?',
        ]);
    }

    public function sayOk(Update $update): void
    {
        $this->bot->sendMessage([
            'chat_id' => $this->getChatId(),
            'text' => 'I’m also OK :)',
        ]);

        $this->nextStep('sayHello');
    }
}
```

### 2. Setup Webhook Handler

[](#2-setup-webhook-handler)

In this example, the Dialog is activated by a command. You can also activate dialogs based on other triggers (like an Update/Message type, or a work inside a Message).

#### 2.1. Setting up a Telegram Command

[](#21-setting-up-a-telegram-command)

Create a command to activate your dialog (Laravel example):

```
use App\Dialogs\HelloDialog;
use KootLabs\TelegramBotDialogs\Laravel\Facades\Dialogs;
use Telegram\Bot\Commands\Command;

final class HelloCommand extends Command
{
    protected $name = 'hello';
    protected $description = 'Start a hello dialog';

    public function handle(): void
    {
        Dialogs::activate(new HelloDialog($this->update->getChat()->id));
    }
}
```

#### 2.2. Webhook Handler Setup

[](#22-webhook-handler-setup)

Handle webhook updates in your controller:

```
use Telegram\Bot\BotsManager;
use KootLabs\TelegramBotDialogs\DialogManager;

final class TelegramWebhookHandler
{
    public function handle(DialogManager $dialogs, BotsManager $botsManager): void
    {
        // Find a \Telegram\Bot\Commands\Command instance for the Update and execute it
        // for /hello command, it should call HelloCommand that will activate HelloDialog
        $update = $bot->commandsHandler(true);

        $dialogs->hasActiveDialog($update)
            ? $dialogs->processUpdate($update) // Run the next step of the active dialog
            : $botsManager->sendMessage([ // send a fallback message
                'chat_id' => $update->getChat()->id,
                'text' => 'No active dialog. Type /hello to start.',
            ]);
    }
}
```

Advanced Usage
--------------

[](#advanced-usage)

### Dialog Class API

[](#dialog-class-api)

```
abstract class Dialog
{
    // Navigation
    public function nextStep(string $stepName): void;
    public function switch(string $stepName): void;
    public function complete(): void;

    // State Management
    public function isAtStart(): bool;
    public function isLastStep(): bool;
    public function isCompleted(): bool;

    // Lifecycle Hooks
    protected function beforeEveryStep(Update $update, int $stepIndex): void;
    protected function afterEveryStep(Update $update, int $stepIndex): void;
    protected function beforeFirstStep(Update $update): void;
    protected function afterLastStep(Update $update): void;

    // Properties Access
    public function getChatId(): int;
    public function getUserId(): ?int;
    public function getTtl(): ?int;
}
```

### DialogManager API

[](#dialogmanager-api)

The `DialogManager` handles:

- Dialog instance persistence
- Step execution
- Dialog activation and switching

Laravel users can use the `Dialogs` facade:

```
use KootLabs\TelegramBotDialogs\Laravel\Facades\Dialogs;

// Activate a dialog
Dialogs::activate($dialog);

// Process an update
Dialogs::processUpdate($update);

// Check for active dialog
Dialogs::hasActiveDialog($update);

// Set custom bot instance
Dialogs::setBot($bot);
```

Contributing
------------

[](#contributing)

Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Testing

[](#testing)

Run the test suite:

```
composer test
```

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

Roadmap
-------

[](#roadmap)

Tasks planned for v1.0:

- Add documentation and examples
- Support for channel bots
- Improve test coverage
- Improve developer experience
- Reach message type validation
- Reach API to validate message types and content

Backward Compatibility Promise
------------------------------

[](#backward-compatibility-promise)

We follow [Semver 2.0](https://semver.org/). Breaking changes are only introduced in major versions.

**Note:**

- Classes marked `@experimental` or `@internal` are not covered by BC promise
- Return value consistency is not guaranteed, only data types
- Argument names (for PHP 8.0+ named arguments) are not part of BC promise

###  Health Score

55

—

FairBetter than 97% of packages

Maintenance71

Regular maintenance activity

Popularity30

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity84

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 78.4% 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.

###  Release Activity

Cadence

Every ~87 days

Recently: every ~56 days

Total

39

Last Release

299d ago

Major Versions

0.x-dev → 1.0.0-beta.12024-11-20

PHP version history (4 changes)0.1.0PHP >=5.5.9

0.3.0PHP >=8.0

0.10.2PHP >=8.0.2

0.14.0PHP >=8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/c9acedf8ce33bd0f1b27bc0de9ea640544c778c1752263254e9591b2f2661dec?d=identicon)[alies-dev](/maintainers/alies-dev)

---

Top Contributors

[![alies-dev](https://avatars.githubusercontent.com/u/5278175?v=4)](https://github.com/alies-dev "alies-dev (232 commits)")[![zarincheg](https://avatars.githubusercontent.com/u/1607662?v=4)](https://github.com/zarincheg "zarincheg (31 commits)")[![dimaodnokoz](https://avatars.githubusercontent.com/u/61492355?v=4)](https://github.com/dimaodnokoz "dimaodnokoz (16 commits)")[![lptn](https://avatars.githubusercontent.com/u/150333538?v=4)](https://github.com/lptn "lptn (8 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (4 commits)")[![CrazyBoy49z](https://avatars.githubusercontent.com/u/3448603?v=4)](https://github.com/CrazyBoy49z "CrazyBoy49z (3 commits)")[![imanghafoori1](https://avatars.githubusercontent.com/u/6961695?v=4)](https://github.com/imanghafoori1 "imanghafoori1 (1 commits)")[![szepeviktor](https://avatars.githubusercontent.com/u/952007?v=4)](https://github.com/szepeviktor "szepeviktor (1 commits)")

---

Tags

laravel-packagetelegram-bot-apilaraveltelegramtelegram-dialog

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/koot-labs-telegram-bot-dialogs/health.svg)

```
[![Health](https://phpackages.com/badges/koot-labs-telegram-bot-dialogs/health.svg)](https://phpackages.com/packages/koot-labs-telegram-bot-dialogs)
```

###  Alternatives

[irazasyed/telegram-bot-sdk

The Unofficial Telegram Bot API PHP SDK

3.3k4.5M84](/packages/irazasyed-telegram-bot-sdk)[exileed/telegram-bot-api

The Telegram Bot API PHP

1514.1k](/packages/exileed-telegram-bot-api)

PHPackages © 2026

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