README

Introduction

PHP client for VK Teams Bot API. Provides a typed interface for sending messages, managing chats, and receiving events via long polling.

Official documentation: https://teams.vk.com/botapi/

Requirements

• PHP 8.2+
• PSR-18 HTTP Client (psr/http-client)
• PSR-17 HTTP Factories (psr/http-factory)
• PSR-3 Logger (psr/log) — optional, for LoggingHttpClient

Installation

composer require belka-tech/php-vk-teams-bot

Quick Start

$bot = new \BelkaTech\VkTeamsBot\Bot(
    new \BelkaTech\VkTeamsBot\Http\HttpClient(
        baseUri: 'https://api.icq.net/bot',
        token: 'YOUR_BOT_TOKEN',
        client: new \GuzzleHttp\Client(
            [
                'connect_timeout' => 4,
                'timeout' => 15,
                'http_errors' => false,
            ],
        ),
        requestFactory: new \GuzzleHttp\Psr7\HttpFactory(),
        streamFactory: new \GuzzleHttp\Psr7\HttpFactory(),
    ),
);

// Send a text message
$bot->messages->sendText(
    chatId: 'YOUR_CHAT_ID',
    text: '<b>Hello!</b>',
);

API

Messages ($bot->messages)

Chats ($bot->chats)

Events API ($bot->events)

Event Listener

Long polling with event dispatching:

$botEventListener = new \BelkaTech\VkTeamsBot\BotEventListener(
    bot: $bot,
);

// Register event handlers
$botEventListener->onMessage(
    function (
        \BelkaTech\VkTeamsBot\Bot $bot,
        \BelkaTech\VkTeamsBot\Event\EventDto $event,
    ): void {
        $bot->messages->sendText(
            chatId: $event->payload['chat']['chatId'],
            text: 'Pong!',
        );
    },
);

$botEventListener->onCommand(
    '/start',
    function (
        \BelkaTech\VkTeamsBot\Bot $bot,
        \BelkaTech\VkTeamsBot\Event\EventDto $event,
    ): void {
        // handle /start command
    },
);

// Start long polling (must be called after all handlers are registered)
$botEventListener->listen(
    pollTime: 30,
    onException: function (
        \Exception $exception,
        \BelkaTech\VkTeamsBot\Event\EventDto $event
    ): void {
        // Log the error
        $this->logger->error('Some text', [
            'event_id' => $event->eventId,
            'event_type' => $event->type,
            'event_payload' => $event->payload,
            'exception' => $exception,
        ]);
        error_log($exception->getMessage());
        
        // Or catch exception to an error reporting system
        $this->sentry->captureException($exception);
        
        // On exception loop continues,
        // you can re-throw the exception to force stop the loop
        throw $exception;
    },
);

// Stop the listener programmatically (e.g. from a handler)
$botEventListener->stop();

If the pcntl extension is available, SIGTERM and SIGINT signals are handled automatically for graceful shutdown. Without pcntl, use $botEventListener->stop() from a handler to stop the loop.

Keyboard

$keyboard = new \BelkaTech\VkTeamsBot\Keyboard\Keyboard();
$keyboard->addRow([
    new \BelkaTech\VkTeamsBot\Keyboard\Button(
        text: 'OK',
        callbackData: 'confirm',
        style: \BelkaTech\VkTeamsBot\Enum\ButtonStyleEnum::Primary,
    ),
    new \BelkaTech\VkTeamsBot\Keyboard\Button(
        text: 'Cancel',
        callbackData: 'cancel',
        style: \BelkaTech\VkTeamsBot\Enum\ButtonStyleEnum::Attention,
    ),
]);

$bot->messages->sendText(
    chatId: '123456',
    text: 'Confirm?',
    inlineKeyboardMarkup: $keyboard,
);

LoggingHttpClient

Decorator for a PSR-18 client that logs requests and responses:

$loggingClient = new \BelkaTech\VkTeamsBot\Http\LoggingHttpClient(
    $psrHttpClient,
    $psrLogger,
);

Parse Mode

HTML is used by default. You can switch to MarkdownV2:

$bot = new \BelkaTech\VkTeamsBot\Bot(
    httpClient: $httpClient,
    parseMode: \BelkaTech\VkTeamsBot\Enum\ParseModeEnum::MarkdownV2,
);

You can also specify parseMode for an individual message:

$bot->messages->sendText(
    chatId: '123456',
    text: '**bold**',
    parseMode: \BelkaTech\VkTeamsBot\Enum\ParseModeEnum::MarkdownV2,
);

Development

make setup   # build image, start container, install dependencies
make test    # run tests
make phpstan # run static analysis
make shell   # enter the container

Other commands: make up, make down, make build, make install.

Alternatives

• https://github.com/dasshit/php-icqbot
• https://github.com/mail-ru-im/bot-java
• https://github.com/mail-ru-im/bot-python
• https://github.com/mail-ru-im/bot-golang

License

• PHP VK Teams Bot package is open-sourced software licensed under the MIT license by BelkaCar.