boshurik/telegram-bot-bundle

Telegram bot bundle

6.0.0 2024-09-27 08:26 UTC

Requires

• php: ^8.0
• ext-curl: *
• ext-json: *
• symfony/console: ^5.4 || ^6.0 || ^7.0
• symfony/event-dispatcher: ^5.4 || ^6.0 || ^7.0
• symfony/framework-bundle: ^5.4 || ^6.0 || ^7.0
• telegram-bot/api: ^2.3.14

Requires (Dev)

• friendsofphp/php-cs-fixer: ~3.23.0
• psalm/plugin-symfony: ^4.0
• symfony/http-client: ^5.4 || ^6.0 || ^7.0
• symfony/messenger: ^5.4 || ^6.0 || ^7.0
• symfony/phpunit-bridge: ^7.0.1
• symfony/security-http: ^5.4 || ^6.0 || ^7.0
• symfony/yaml: ^5.4 || ^6.0 || ^7.0
• vimeo/psalm: ~4.30.0

Suggests

• symfony/http-client: Required to use third party http client
• symfony/messenger: Required to handle messages with queues
• symfony/security-guard: Required to implement user authentication through Telegram

MIT

• Alexander Borisov
• Community

README

Telegram bot bundle on top of telegram-bot/api library

Examples

See example project

Installation

Composer

$ composer require boshurik/telegram-bot-bundle

If you are using symfony/flex all you need is to set TELEGRAM_BOT_TOKEN environment variable

Register the bundle

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new BoShurik\TelegramBotBundle\BoShurikTelegramBotBundle,
    );
    // ...
}

Add routing for webhook

BoShurikTelegramBotBundle:
    resource: "@BoShurikTelegramBotBundle/Resources/config/routing.php"
    prefix: /_telegram/%telegram_bot_route_secret%

or for multiple bots:

BoShurikTelegramBotBundle:
    resource: "@BoShurikTelegramBotBundle/Resources/config/routing.php"
    prefix: /_telegram/{bot}/%telegram_bot_route_secret%

Configuration

boshurik_telegram_bot:
    api:
        token: "%telegram_bot_api_token%"
        proxy: "socks5://127.0.0.1:8888"

or for multiple bots:

boshurik_telegram_bot:
    api:
        default_bot: first
        bots:
            first: "%first_telegram_bot_api_token%"
            second: "%second_telegram_bot_api_token%"
        proxy: "socks5://127.0.0.1:8888"

Usage

API

To get default bot api:

use TelegramBot\Api\BotApi;
public function __construct(private BotApi $api)

For multiple bots:

use BoShurik\TelegramBotBundle\Telegram\BotLocator;
use TelegramBot\Api\BotApi;

public function foo(BotLocator $botLocator)
{
    /** @var BotApi $api */
    $api = $botLocator->get('first');
}

or use argument with type TelegramBot\Api\BotApi and name pattern /\${name}(Bot|BotApi|Api)?$/

use TelegramBot\Api\BotApi;
public function __construct(private BotApi $firstBotApi)

For more info see Usage section in telegram-bot/api library

Getting updates

bin/console telegram:updates
bin/console telegram:updates first

For more information see official documentation

Webhook

Set

bin/console telegram:webhook:set [url-or-hostname] [<path-to-certificate>]
bin/console telegram:webhook:set [url-or-hostname] [<path-to-certificate>] --bot first

If url-or-hostname is not set command will generate url based on request context

Unset

bin/console telegram:webhook:unset
bin/console telegram:webhook:unset first

For more information see official documentation

Async command processing

To improve performance, you can leverage Messenger to process webhooks later via a Messenger transport.

composer req symfony/messenger

# config/packages/messenger.yaml
framework:
    messenger:
        transports:
            async: "%env(MESSENGER_TRANSPORT_DSN)%"

        routing:
            'BoShurik\TelegramBotBundle\Messenger\TelegramMessage': async

Adding commands

Commands must implement \BoShurik\TelegramBotBundle\Telegram\Command\CommandInterface

There is \BoShurik\TelegramBotBundle\Telegram\Command\AbstractCommand you can start with

To register command: add tag boshurik_telegram_bot.command to service definition

app.telegram.command:
    class: AppBundle\Telegram\Command\SomeCommand
    tags:
        - { name: boshurik_telegram_bot.command }

If you use autoconfigure tag will be added automatically

For application with multiple bots you need to pass bot id:

app.telegram.command:
    class: AppBundle\Telegram\Command\SomeCommand
    tags:
        - { name: boshurik_telegram_bot.command, bot: first }

If you need to use same command for multiple bots you must add multiple tags for each bot:

app.telegram.command:
    class: AppBundle\Telegram\Command\SomeCommand
    tags:
        - { name: boshurik_telegram_bot.command, bot: first }
        - { name: boshurik_telegram_bot.command, bot: second }

There is predefined \BoShurik\TelegramBotBundle\Telegram\Command\HelpCommand. It displays commands which additionally implement \BoShurik\TelegramBotBundle\Telegram\Command\PublicCommandInterface

You need to register it:

app.telegram.command.help:
    class: BoShurik\TelegramBotBundle\Telegram\Command\HelpCommand
    arguments:
        - '@boshurik_telegram_bot.command.registry.default'
    tags:
        - { name: boshurik_telegram_bot.command }

or for multiple bots:

app.telegram.command.help:
    class: BoShurik\TelegramBotBundle\Telegram\Command\HelpCommand
    arguments:
        - '@boshurik_telegram_bot.command.registry.first'
    tags:
        - { name: boshurik_telegram_bot.command, bot: first }

Events

For more complex application (e.g. conversations) you can listen for BoShurik\TelegramBotBundle\Event\UpdateEvent event

/**
 * @param UpdateEvent $event
 */
public function onUpdate(UpdateEvent $event)
{
    $update = $event->getUpdate();
    $message = $update->getMessage();
}

Login with Telegram

This bundle supports login through Telegram Api

If you want to allow your Bot's users to login without requiring them to register again follow these instructions.