README

Tueen Telegram 👑

The Royal Telegram Bot SDK for Modern PHP
Part of the Tueen ecosystem — "The Queen of Telegram"

⚡ Highlights

👑 Complete Bot API Coverage — Strictly-typed methods, models, and enums for all Telegram features.
💎 Modern PHP 8.4+ Architecture — Built with property hooks, asymmetric visibility, and zero legacy baggage.
🧭 Expressive Routing — Commands, callback queries, regex matchers, and PHP 8 attribute controllers.
⌨️ Fluent Keyboards & Safe Formatting — Intuitive Inline/Reply builders and entity-safe HTML/MarkdownV2 styling.
💬 Conversational Flows & Navigation — Multi-step state machines, hierarchical screen stacks, and zero-flicker UI transitions.
🔄 Production Webhook & Polling — Secret token validation and persistent worker support (FrankenPHP, Swoole, RoadRunner).
🚀 Zero-Config App & Web Dashboard — Instant bot launcher with a CLI toolkit and an embedded management dashboard.
🔌 Resilient HTTP Pipeline — Persistent connection pooling, automatic rate-limit backoff, and PSR-3 logging.
🛡️ Dual Error Modes — Choose between traditional exceptions or typed error objects with universal status checks.
🧪 In-Memory Testing — First-class testing fakes with expressive assertions and zero HTTP overhead.

📦 Requirements & Installation

PHP 8.4 or higher (fully compatible with PHP 8.5+)
Composer 2.x
Extensions: json, curl or stream wrappers, mbstring

composer require tueen/telegram

🚀 Quickstart

Build an interactive bot with command routing, inline buttons, and safe HTML formatting:

<?php

declare(strict_types=1);

use Tueen\Telegram\Telegram;
use Tueen\Telegram\Types\User;
use Tueen\Telegram\Types\Update;
use Tueen\Telegram\Keyboards\InlineKeyboard;
use Tueen\Telegram\Formatting\Text;

require __DIR__ . '/vendor/autoload.php';

$bot = new Telegram('YOUR_BOT_TOKEN');

// Handle /start command with auto-wired User parameter
$bot->onCommand('start', function (User $user, Telegram $bot) {
    $keyboard = InlineKeyboard::make()
        ->row()
            ->callback('✨ Explore', 'action:explore')
            ->url('📚 Documentation', 'https://tueen.github.io/telegram/')
        ->build();

    $bot->reply(
        Text::html()
            ->bold("Welcome, {$user->firstName}! 👋")->line()
            ->plain("Ready to build modern Telegram bots with PHP 8.4+?"),
        replyMarkup: $keyboard
    );
});

// Handle callback query button tap
$bot->onCallbackQuery('action:explore', function (Update $update, Telegram $bot) {
    $bot->answerCallbackQuery($update->callbackQuery->id);
    $bot->reply('Explore full guides and examples at https://tueen.github.io/telegram/');
});

// Start long-polling (or configure WebhookMode for production)
$bot->usePollingMode();
$bot->run();

💡 Looking for zero-config single-file bootstrapping and the embedded Web Dashboard? Check out the Zero-Config App & Web Dashboard Guide.

📖 Documentation

Complete guides, real-world examples, configuration options, and API catalogs are available in our official documentation:

👉 https://tueen.github.io/telegram/

For AI coding assistants (Cursor, Claude, ChatGPT), machine-readable context and offline skill packages are available at the AI & LLM Context Hub.

📜 License

tueen/telegram is open-sourced software licensed under the MIT License.

tueen / telegram

Package info

Security

Statistics