README

An SDK written in PHP to communicate with the Telegram Bot API.

Last supportet Bot API Version: 9.3 (2025-12-31)

All useful Information to Telegram Bots can you find on the official Website.

This is only an SDK, not a Bot itself.

Disclaimer

This project and its author are neither associated nor affiliated with Telegram in any way.

License

This project is released under the MIT License.

Requirements

• PHP >= 8.4

Installation

The easiest way is the installation via Composer: composer require gfn/telegram-php-sdk

Alternatively you can add this GIT-Repository to your composer.json:

{
	"repositories": [
		{
			"type": "git",
			"url": "https://gitlab.german-furs.net/german-furs/telegram-php-sdk.git",
			"no-api": true
		}
	]
}

Usage

First you need to create a bot via BotFather and authorize it. Save the token and hold it save.

All classes have links to the original documentation. If you are not sure how to use the class, check out the documentation.

Examples requests outgoing

getMe

With the getMe method, you can request all information about your bot.

$bot_token	= 'xxx';
$get_me		= new \GfnTelegramPhpSdk\Core\Request\GetMe();

try {
	$get_me->execute($bot_token)
	var_dump($get_me->getResponse());
} catch (\GfnTelegramPhpSdk\Exception\GfnTelegramPhpSdkException $e) {
	var_dump($e);
}

sendMessage

With the sendMessage method, you can send a message to a user or chat.

$bot_token	= 'xxx';
$chat_id	= 000;

$sm		= new SendMessage();
$sm->chat_id	= $chat_id;
$sm->text	= 'Test Message';

// Example with inline buttons.
// Buttons One & Two are on line 1, Button Three is on line 2.
// Each InlineKeyboardButton needs a purpose, so I used the callback_data.
$button_one_data	= [
	'text'		=> 'Button One',
	'callback_data'	=> 'callback_one'
];
$button_two_data	= [
	'text'		=> 'Button Two',
	'callback_data'	=> 'callback_two'
];
$button_three_data	= [
	'text'		=> 'Button Three',
	'callback_data'	=> 'callback_three'
];

$inline_keyboard_markup	= new \GfnTelegramPhpSdk\Core\Type\InlineKeyboardMarkup(['inline_keyboard' => [[$button_one_data, $button_two_data],[$button_three_data]]]);
$sm->reply_markup	= $inline_keyboard_markup;

try {
	$sm->execute($bot_token)
	var_dump($sm->getResponse());
} catch (\GfnTelegramPhpSdk\Exception\GfnTelegramPhpSdkException $e) {
	var_dump($e);
}

File Upload

To send files to users or chats, use the respective methods with file paths or file IDs.

Sending Documents

Use sendDocument to send general files like ZIP archives, PDFs, etc.

$bot_token	= 'xxx';
$chat_id	= 000;

// Send a ZIP file from local file system
$sd		= new \GfnTelegramPhpSdk\Core\Request\SendDocument();
$sd->chat_id	= $chat_id;
$sd->document	= new \CURLFile('/path/to/archive.zip', 'application/zip', 'archive.zip');
$sd->caption	= 'Here is your archive';

try {
	$sd->execute($bot_token);
	var_dump($sd->getResponse());
} catch (\GfnTelegramPhpSdk\Exception\GfnTelegramPhpSdkException $e) {
	var_dump($e);
}

// Alternatively, use a file_id from a previously uploaded file
$sd->document = 'BQACAgIAAxkBAAI...'; // file_id from previous upload

Sending Photos

Use sendPhoto to send images.

$bot_token	= 'xxx';
$chat_id	= 000;

// Send a photo from local file system
$sp		= new \GfnTelegramPhpSdk\Core\Request\SendPhoto();
$sp->chat_id	= $chat_id;
$sp->photo	= new \CURLFile('/path/to/photo.jpg', 'image/jpeg', 'photo.jpg');
$sp->caption	= 'This is a photo';

try {
	$sp->execute($bot_token);
	var_dump($sp->getResponse());
} catch (\GfnTelegramPhpSdk\Exception\GfnTelegramPhpSdkException $e) {
	var_dump($e);
}

// Alternatively, use a file_id from a previously uploaded file
$sp->photo = 'AgACAgIAAxkBAAI...'; // file_id from previous upload

Examples requests incoming

All incoming traffic is checked. If the request does not come from the Telegram network, it will be ignored.

It's important to send a reply in all possible cases, even if Telegram doesn't process it. It's only correct if you receive a response to your request.

If you do not send code 200 as a reply, Telegram will consider this a failed communication attempt and try to send the message again later.

// Cancel the request if it does not come from the Telegram network or is invalid
try {
	if (!Update::isValidRequest()) {
		header('Content-Type: application/json');
		echo '{"success":false,"status":403}';

		exit;
	}
} catch (\GfnTelegramPhpSdk\Exception\GfnTelegramPhpSdkException) {
	header('Content-Type: application/json');
	echo '{"success":false,"status":400}';

	exit;
}

$request_class_name	= Update::getRequestType();
$type_name		= Update::getRequestName();

// Unknown type of request
if (empty($request_class_name) || empty($type_name)) {
	header('Content-Type: application/json');
	echo '{"success":false,"status":404}';

	exit;
}

try {
	$request_class	= new $request_class_name(Update::getRequestDecoded()[$type_name]);

	if ($request_class instanceof GfnTelegramPhpSdk\Core\Type\BusinessConnection) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\BusinessMessagesDeleted) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\CallbackQuery) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\ChatBoostRemoved) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\ChatBoostUpdated) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\ChatJoinRequest) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\ChatMemberUpdated) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\ChosenInlineResult) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\InlineQuery) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\Message) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\MessageReactionCountUpdated) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\MessageReactionUpdated) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\PaidMediaPurchased) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\Poll) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\PollAnswer) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\PreCheckoutQuery) {
		// do code
	} elseif ($request_class instanceof GfnTelegramPhpSdk\Core\Type\ShippingQuery) {
		// do code
	} else {
		header('Content-Type: application/json');
		echo '{"success":false,"status":404}';

		exit;
	}
} catch (\GfnTelegramPhpSdk\Exception\GfnTelegramPhpSdkException $e) {
	header('Content-Type: application/json');
	echo '{"success":false,"status":400}';

	exit;
}

// Request was successful
header('Content-Type: application/json');
echo '{"success":true,"status":200}';