vjik/telegram-bot-api

PHP library for working with Telegram API

0.8 2025-02-15 09:00 UTC

Requires

• php: ^8.2
• php-http/multipart-stream-builder: ^1.4.2
• psr/http-client: ^1.0
• psr/http-factory: ^1.1
• psr/http-message: ^1.1 || ^2.0

Requires (Dev)

• ext-curl: *
• bamarni/composer-bin-plugin: ^1.8.2
• httpsoft/http-message: ^1.1.6
• php-http/curl-client: ^2.3.3
• phpunit/phpunit: ^11.5.7
• psr/log: ^3.0.2
• yiisoft/test-support: ^3.0.1

Suggests

• ext-curl: To use `CurlTransport`.
• psr/log: To log requests to Telegram Bot API and response handling errors.

BSD-3-Clause

• Sergei Predvoditelev

• api
• bot
• telegram

README

The package provides a simple and convenient way to interact with the Telegram Bot API.

✔️ Telegram Bot API 8.3 (February 12, 2025) is fully supported.

Requirements

• PHP 8.2 or higher.

Installation

The package can be installed with Composer:

composer require vjik/telegram-bot-api

General usage

To make requests to the Telegram Bot API, you need to create an instance of the TelegramBotApi class.

use Vjik\TelegramBot\Api\TelegramBotApi;

// API
$api = new TelegramBotApi(
    // Telegram bot authentication token
    '110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw',
);

Now you can use the $api instance to interact with the Telegram Bot API. Method names are the same as in the Telegram Bot API documentation. For example:

use Vjik\TelegramBot\Api\Type\InputFile

// Specify a URL for outgoing webhook
$api->setWebhook('https://example.com/webhook');

// Send text message
$api->sendMessage(
    chatId: 22351, 
    text: 'Hello, world!',
);

// Send local photo
$api->sendPhoto(
    chatId: 22351, 
    photo: InputFile::fromLocalFile('/path/to/photo.jpg'),
);

The result will be either a FailResult instance (occurring on an error) or an object of the corresponding type (occurring on success). For example:

// Result is an array of `Vjik\TelegramBot\Api\Update\Update` objects
$updates = $api->getUpdates();

Documentation

TelegramBotApi

TelegramBotApi constructor parameters:

• $token (required) — Telegram bot authentication token;
• $baseUrl — the base URL for Telegram Bot API requests (default https://api.telegram.org).
• $transport — the transport to make requests to Telegram Bot API (cURL will be used by default).
• $logger — the PSR-3 compatible logger to log requests to Telegram Bot API and response handling errors. See logging for more information.

Method names are the same as in the Telegram Bot API documentation.

Files

File URL

Use TelegramBotApi::makeFileUrl() method to make a URL for downloading a file from the Telegram server. For example:

/**
 * @var \Vjik\TelegramBot\Api\TelegramBotApi $api
 * @var \Vjik\TelegramBot\Api\Type\File $file 
 */
 
// By `File` instance
$url = $api->makeFileUrl($file);

// By file path is taken from the Telegram response
$url = $api->makeFileUrl('photos/file_2');

File downloading

Use TelegramBotApi::downloadFile() and TelegramBotApi::downloadFileTo() methods to download a file from the Telegram server. For example:

/**
 * @var \Vjik\TelegramBot\Api\TelegramBotApi $api
 * @var \Vjik\TelegramBot\Api\Type\File $file
 */
 
// Get file content by `File` instance
$fileContent = $api->downloadFile($file);

// Get file content by file path
$fileContent = $api->downloadFile('photos/file_2');

// Download and save file by `File` instance
$fileContent = $api->downloadFileTo($file, '/local/path/to/file.jpg');

// Download and save file by file path
$fileContent = $api->downloadFileTo('photos/file_2', '/local/path/to/file.jpg');

Guides

• Transport
• Logging
• Webhook handling
• Custom requests
• Internals

If you have any questions or problems with this package, use author telegram chat for communication.

License

The vjik/telegram-bot-api is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Credits

The package is inspired by Botasis code originally created by Viktor Babanov.