koot-labs/telegram-bot-dialogs

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

0.7.0 2024-04-21 20:54 UTC

Requires

• php: >=8.0
• illuminate/support: ^8.0 || ^9.0 || ^10.0 || ^11.0
• irazasyed/telegram-bot-sdk: ^3.1
• predis/predis: ^1.0 || ^2.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.54
• phpunit/phpunit: ^10.5 || ^11.0

MIT

• laravel
• telegram
• telegram-dialog

README

Dialogs plugin for Telegram Bot API PHP SDK

The extension for Telegram Bot API PHP SDK v3.1+ that allows to implement dialogs for telegram bots.

About this fork

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.

Installation

You can easily install the package using Composer:

composer require koot-labs/telegram-bot-dialogs

Package requires PHP >= 8.0

Usage

1. Create a Dialog class
2. Create a Telegram command and start a Dialog from Command::handle().
3. Setup your controller class to proceed active Dialog on income webhook request.

1. Create a Dialog class

Each dialog should be implemented as class that extends basic Dialog as you can see in HelloExampleDialog or the code bellow:

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

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

    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 :)",
        ]);
    }

    public function sayBye(Update $update): void
    {
        $this->bot->sendMessage([
            'chat_id' => $this->getChatId(),
            'text' => 'Bye!',
        ]);
        $this->jump('sayHello');
    }
}

2. Create a Telegram command

To initiate a dialog please use DialogManager (or, if you use Laravel, Dialogs Facade) — it will care about storing and recovering Dialog instance state between steps/requests. To execute the first and next steps please call Dialogs::procceed() method with update object as an argument. Also, it is possible to use dialogs with Telegram commands and DI through type hinting.

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

final class HelloCommand extends Command
{
    /** @var string Command name */
    protected $name = 'hello';

    /** @var string Command description */
    protected $description = 'Just say "Hello" and ask few questions';

    public function handle(): void
    {
        $bot = $this->getTelegram();
        Dialogs::activate(new HelloExampleDialog($this->update->getChat()->id, $bot));
    }
}

3. Setup your controller

Process request inside your Laravel webhook controller:

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

final class TelegramWebhookController
{
    public function handle(DialogManager $dialogs, BotsManager $botsManager): void
    {
        $bot = $botsManager->bot('your-bot-name');
        $update = $bot->commandsHandler(true);

        // optional, for multi-bot applications only, when a given bot is not a default one
        $dialogs->setBot($bot);

        $dialogs->exists($update)
            ? $dialogs->proceed($update)
            : $botsManager->bot('your-bot-name')->sendMessage([ // fallback message
                'chat_id' => $update->getChat()->id,
                'text' => 'There is no active dialog at this moment.',
            ]);
    }
}

Dialog class API

• start(\Telegram\Bot\Objects\Update $update) - Start the dialog from the first step
• proceed(\Telegram\Bot\Objects\Update $update) - Proceed the dialog to the next step
• isEnd() - Check the end of the dialog
• 🔐 end() - End dialog
• 🔐 jump(string $stepName) - Jump to the particular step, where $step is the public method name
• 🔐 remember(string $key, mixed $value) - Add a new key-value to Dialog::$memory array to make this data available on next steps
• 🔐 forget(string $key) - Remove a value from Dialog::$memoryby key.

DialogManager class API

ℹ️ Dialogs Facade proxies calls to DialogManager class.

• setBot(\Telegram\Bot\Api $bot) - Use non-default Bot for API calls
• activate(\KootLabs\TelegramBotDialogs\Dialog $dialog) - Activate a new Dialog (without running it)
• proceed(\Telegram\Bot\Objects\Update $update) - Run the next step handler for the existing Dialog
• exists(\Telegram\Bot\Objects\Update $update) - Check for existing Dialog

ToDo

• Add AI API support (e.g. LUIS, Dataflow)
• Improve documentation and examples
• Improve stability and DX for channel bots
• Improve test coverage

Backward compatibility promise

Dialogs package uses Semver 2.0. This means that versions are tagged with MAJOR.MINOR.PATCH. Only a new major version will be allowed to break backward compatibility (BC).

Classes marked as @experimental or @internal are not included in our backward compatibility promise. You are also not guaranteed that the value returned from a method is always the same. You are guaranteed that the data type will not change.

PHP 8 introduced named arguments, which increased the cost and reduces flexibility for package maintainers. The names of the arguments for methods in Dialogs is not included in our BC promise.