README

Dialogs Plugin for Telegram Bot API PHP SDK

A powerful extension for Telegram Bot API PHP SDK v3.1+ that enables dialog-based interactions in your Telegram bots.

About
Features
Installation
- Laravel Integration
- Framework-agnostic Usage
Basic Usage
Advanced Usage
- Dialog Class API
- DialogManager API
Testing
Contributing
License
Roadmap

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?

The Original package is not maintained anymore 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, PHP 8+ and Laravel features, focus on stability, better DX and readability.

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

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

Install via Composer:

composer require koot-labs/telegram-bot-dialogs

Laravel Integration

The package automatically registers \KootLabs\TelegramBotDialogs\Laravel\DialogsServiceProvider
Publish the configuration:

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

This creates config/telegram.php with these environment variables:

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

Framework-agnostic Usage

For non-Laravel applications, see our framework-agnostic guide.

Basic Usage

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<string> 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

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

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

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

Dialog Class API

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

    // State Management
    public function isAtStart(): bool;
    public function isLastStep(): bool;
    public function isComplete(): 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 ttl(): int;
}

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

Contributions are welcome! Please see our Contributing Guide for details.

Testing

Run the test suite:

composer test

License

This package is open-sourced software licensed under the MIT license.

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

We follow Semver 2.0. 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

koot-labs / telegram-bot-dialogs

Maintainers

Details