README

PHP SDK for the Telegram Bot API. Typed request/response objects, Guzzle HTTP client, and coverage aligned with Bot API 10.2 (July 2026).

Requirements

• PHP >= 8.1
• Extensions: json, curl
• Composer dependencies: guzzlehttp/guzzle ^7.9, psr/log ^3.0

Installation

composer require yabx/telegram

Features

• Strongly typed Yabx\Telegram\Objects\* models for available types
• One method per Bot API method on Yabx\Telegram\BotApi, matching available methods
• request() for direct API calls when you need maximum flexibility
• Optional PSR-3 logging and custom Guzzle / base URL for tests or proxies
• Webhook parsing from raw JSON or php://input
• getUpdates long polling support

Quick start

use Yabx\Telegram\BotApi;

$token = getenv('TELEGRAM_BOT_TOKEN');
$bot = new BotApi($token);

$me = $bot->getMe();
$chatId = 123456789; // Telegram user/group/channel id from an allowed update context
$sent = $bot->sendMessage($chatId, 'Bot is up. Connected as @' . ($me->getUsername() ?? 'bot'));

Client options

use GuzzleHttp\RequestOptions;
use Psr\Log\LoggerInterface;
use Yabx\Telegram\BotApi;

/** @var LoggerInterface $logger e.g. Monolog, Symfony Bridge, … */
$bot = new BotApi(
    $token,
    [
        RequestOptions::TIMEOUT => 30,
        RequestOptions::VERIFY => true,
    ],
    $logger,
    'https://api.telegram.org', // optional custom API host
);

Send messages (text, parse mode, reply)

use Yabx\Telegram\Objects\ReplyParameters;

$bot->sendMessage(
    chatId: $chatId,
    text: 'Hello, <b>world</b>',
    parseMode: 'HTML',
);

$bot->sendMessage(
    chatId: $chatId,
    text: 'Replying…',
    replyParameters: new ReplyParameters(messageId: $originalMessageId),
);

Inline keyboard

use Yabx\Telegram\Objects\InlineKeyboardButton;
use Yabx\Telegram\Objects\InlineKeyboardMarkup;

$keyboard = new InlineKeyboardMarkup([
    [
        new InlineKeyboardButton('Docs', url: 'https://core.telegram.org/bots/api'),
        new InlineKeyboardButton('Tap me', callbackData: 'demo:1'),
    ],
]);

$bot->sendMessage($chatId, 'Pick an action:', replyMarkup: $keyboard);

Reply keyboard (custom keyboard)

use Yabx\Telegram\Objects\KeyboardButton;
use Yabx\Telegram\Objects\ReplyKeyboardMarkup;

$markup = new ReplyKeyboardMarkup(
    keyboard: [
        [new KeyboardButton('Yes'), new KeyboardButton('No')],
        [new KeyboardButton('Cancel')],
    ],
    resizeKeyboard: true,
    oneTimeKeyboard: true,
);

$bot->sendMessage($chatId, 'Your choice?', replyMarkup: $markup);

Photo from disk (multipart upload)

If the path exists on disk, the client opens the file and sends it as multipart automatically:

$bot->sendPhoto(
    chatId: $chatId,
    photo: '/tmp/snapshot.jpg',
    caption: 'Snapshot',
    parseMode: 'HTML',
);

Webhooks

Register and inspect the webhook:

$bot->setWebhook(
    url: 'https://example.com/telegram/webhook',
    allowedUpdates: ['message', 'callback_query'],
    secretToken: getenv('WEBHOOK_SECRET'),
);

$info = $bot->getWebhookInfo();

Handle an incoming POST body (typical PHP endpoint):

use Yabx\Telegram\BotApi;

// Reads php://input and builds an Update (throws if body is empty / invalid JSON)
$update = BotApi::getUpdateFromRequest();

// Or parse a string you already have:
$update = BotApi::getUpdateFromJson($requestBody);

Then branch on the update payload:

if ($message = $update->getMessage()) {
    $chatId = $message->getChat()->getId();
    $text = $message->getText();
    $photos = $message->getPhotos();
    $video = $message->getVideo();
    $document = $message->getDocument();
    // … same pattern for stickers, polls, forwarded messages, etc.
}

if ($callback = $update->getCallbackQuery()) {
    $bot->answerCallbackQuery($callback->getId(), text: 'OK');
}

Long polling (getUpdates)

$offset = 0;

while (true) {
    $updates = $bot->getUpdates(offset: $offset, timeout: 50);

    foreach ($updates as $update) {
        $offset = $update->getUpdateId() + 1;

        if ($msg = $update->getMessage()) {
            $bot->sendMessage($msg->getChat()->getId(), 'Echo: ' . ($msg->getText() ?? ''));
        }
    }
}

Low-level request()

Useful for new API parameters before a dedicated method exists, or rare calls:

$result = $bot->request('getChat', ['chat_id' => $chatId]);

Objects with a toArray() method are normalized automatically. Upload methods on BotApi already set multipart where needed.

Last raw API response

After each call, the decoded JSON envelope (including ok, result, description, etc.) is available:

$bot->sendMessage($chatId, 'Hi');
$envelope = $bot->getLastResponse();

Error handling

Failed Bot API responses throw Yabx\Telegram\Exception with Telegram’s error_code as the exception code when present:

use Yabx\Telegram\Exception as TelegramApiException;

try {
    $bot->sendMessage($chatId, 'Ping');
} catch (TelegramApiException $e) {
    // $e->getCode() often matches Telegram's error_code
    error_log($e->getMessage());
}

Project layout

Testing

composer install
composer test

Optional coverage report (requires the PCOV extension locally):

# Ubuntu/Debian — match your PHP version (php -v)
sudo apt install php8.3-pcov   # or php8.5-pcov, php8.2-pcov, …

composer test:coverage

HTML report in build/coverage/:

composer test:coverage-html

If PCOV is not installed, composer test:coverage prints installation hints instead of a cryptic PHPUnit error. CI collects coverage with PCOV on PHP 8.3 (job coverage in .github/workflows/tests.yml).

Tests use PHPUnit 10.5+ (PHP 8.1) or 11+ (PHP 8.2+) with Guzzle MockHandler for HTTP integration tests. Fixtures live in tests/Fixtures/.

Coverage phases

InputPollMedia / InputPollOptionMedia are PHP interfaces; implementing classes (InputMediaPhoto, InputMediaLink, …) are covered in the round-trip manifest and via sendPoll contract tests.

Static analysis and coverage gate

composer phpstan          # PHPStan level 2 on src/
composer test:coverage    # fails if line coverage drops below 57%

Bot API 10.2 examples

Ephemeral messages

$bot->sendMessage($chatId, 'Only you can see this', receiverUserId: $userId, callbackQueryId: $queryId);
$bot->editEphemeralMessageText($chatId, $userId, $ephemeralMessageId, 'Updated');
$bot->deleteEphemeralMessage($chatId, $userId, $ephemeralMessageId);

Rich message blocks

use Yabx\Telegram\Objects\InputRichBlockParagraph;
use Yabx\Telegram\Objects\InputRichMessage;

$bot->sendRichMessage($chatId, new InputRichMessage(
    blocks: [new InputRichBlockParagraph(text: 'Hello')],
));

Bot API 10.1 examples

Business connection

$connection = $bot->getBusinessConnection('bc-1');
$bot->readBusinessMessage('bc-1', $chatId, $messageId);

Stories (managed business account)

use Yabx\Telegram\Objects\InputStoryContentPhoto;

$bot->postStory(
    businessConnectionId: 'bc-1',
    content: new InputStoryContentPhoto(type: 'photo', photo: '/tmp/story.jpg'),
    activePeriod: 86400,
    caption: 'News',
);

Gifts and Stars

$gifts = $bot->getAvailableGifts();
$bot->sendGift($userId, 'gift-id', text: 'Enjoy!');
$balance = $bot->getMyStarBalance();

Rich messages

use Yabx\Telegram\Objects\InputRichMessage;

$bot->sendRichMessage($chatId, new InputRichMessage(html: '<b>Hello</b>'));

To add coverage for a new object, append an entry to the appropriate file under tests/Fixtures/roundtrip/ (merged by roundtrip.php):

SomeObject::class => ['field' => 'value'],

License

MIT (see composer.json).

See also

• Telegram Bot API documentation
• Creating a bot with BotFather