telegrambot-api

The Client class provides a high-level interface for handling updates, commands, and running the bot loop. You can register command handlers with $bot->command() and general update handlers with $bot->on().

require_once "vendor/autoload.php";

try {
    $bot = new \TelegramBot\Api\Client('YOUR_BOT_API_TOKEN');

    // Handle /ping command
    $bot->command('ping', function ($message) use ($bot) {
        $bot->sendMessage($message->getChat()->getId(), 'pong!');
    });
    
    // Handle all text messages
    $bot->on(function (\TelegramBot\Api\Types\Update $update) use ($bot) {
        $message = $update->getMessage();
        $id = $message->getChat()->getId();
        $bot->sendMessage($id, 'Your message: ' . $message->getText());
    }, function () {
        return true;
    });
    
    $bot->run();

} catch (\TelegramBot\Api\Exception $e) {
    $e->getMessage();
}

Install the library using Composer to include it in your PHP project.

$ composer require telegram-bot/api

If you are using a custom local bot API server, pass the server URL as the fourth argument to the Client constructor.

use TelegramBot\Api\Client;
$token = 'YOUR_BOT_API_TOKEN';
$bot = new Client($token, null, null, 'http://localhost:8081');

To interact with the Telegram Bot API, instantiate the TelegramBot\Api\Client class. You must provide your Telegram Bot API token. Optionally, you can provide a custom HttpClientInterface implementation or a specific API endpoint.

use TelegramBot\Api\Client;

$client = new Client('YOUR_BOT_TOKEN');

If you are using webhooks, call the run() method. This method reads the raw request body from php://input, validates the JSON, and processes the resulting Update through the registered event handlers.

// In your webhook entrypoint script
$client->run();

You can attach different types of keyboards to messages using ReplyKeyboardMarkup for standard button layouts or InlineKeyboardMarkup for buttons attached directly to the message.

$bot = new \TelegramBot\Api\BotApi('YOUR_BOT_API_TOKEN');

// Reply Keyboard (standard buttons)
$keyboard = new \TelegramBot\Api\Types\ReplyKeyboardMarkup(array(array("one", "two", "three")), true); // true for one-time keyboard
$bot->sendMessage($chatId, $messageText, null, false, null, $keyboard);

// Inline Keyboard (buttons with URLs/callbacks)
$keyboard = new \TelegramBot\Api\Types\Inline\InlineKeyboardMarkup([
    [
        ['text' => 'link', 'url' => 'https://core.telegram.org']
    ]
]);
$bot->sendMessage($chatId, $messageText, null, false, null, $keyboard);

To send multiple photos or videos together, use ArrayOfInputMedia and add items using InputMediaPhoto or InputMediaVideo.

$bot = new \TelegramBot\Api\BotApi('YOUR_BOT_API_TOKEN');
$media = new \TelegramBot\Api\Types\InputMedia\ArrayOfInputMedia();
$media->addItem(new \TelegramBot\Api\Types\InputMedia\InputMediaPhoto('https://avatars3.githubusercontent.com/u/9335727'));
$media->addItem(new \TelegramBot\Api\Types\InputMedia\InputMediaPhoto('https://avatars3.githubusercontent.com/u/9335727'));

$bot->sendMediaGroup($chatId, $media);

You can inject a custom HTTP client into the Client by using the SymfonyHttpClient wrapper. This is useful if you want to use Symfony's HttpClient instead of the default implementation.

use Symfony\Component\HttpClient\HttpClient;
use TelegramBot\Api\Client;
use TelegramBot\Api\Http\SymfonyHttpClient;

$token = 'YOUR_BOT_API_TOKEN';
$bot = new Client($token, null, new SymfonyHttpClient(HttpClient::create()));

The BotApi class provides a direct wrapper for Telegram Bot API methods. You can use it to send messages, documents, or media groups by providing your bot token and the target chatId.

$bot = new \TelegramBot\Api\BotApi('YOUR_BOT_API_TOKEN');

// Send a simple text message
$bot->sendMessage($chatId, $messageText);

// Send a document using CURLFile
$document = new \CURLFile('document.txt');
$bot->sendDocument($chatId, $document);

Use the command() method to register a handler for a specific bot command (e.g., /start). The command name is the string following the slash.

When a command is triggered, the provided Closure is executed. The Client automatically parses the command and passes the following arguments to your closure based on the number of required parameters:

1. The Message object representing the command message.
2. Any additional parameters passed in the command text (space-separated).

$client->command('start', function (\TelegramBot\Api\Types\Message $message) {
    // Handle /start command
    $message->reply('Hello!');
});