estaheri / easytel
An easy to use php library for using telegram bot api
Requires
- php: >=8.2
- estaheri/json: ^1.0.1
- guzzlehttp/guzzle: ^7.8
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 10:34:26 UTC
README
An easy to use, fully object oriented PHP library for the
Telegram Bot API.
Every Bot API method and type exists as a real PHP class, generated from the
official documentation — so your IDE already knows everything.
Table of contents
- Introduction
- Requirements
- Installation
- Quick start
- Sending requests
- Receiving updates
- Working with types
- Sending files
- Cookbook
- Advanced
- Project structure
- Testing
- Notes on generated code
- Contributing
- License
- Links
Introduction
EasyTel is just a library — it does not ship a router, an update loop or a framework. Drop it next to Laravel, Symfony, CodeIgniter, Slim, plain PHP, or anything else.
What you get:
- Complete coverage — 193 method classes and 425 type classes, generated from the official Bot API documentation (currently Bot API 10.4).
- Full IDE support — every method and type is a real class with typed
properties and phpdoc copied from Telegram.
Ctrl+Spaceworks for method parameters, nested objects, enum-like string values and update fields. - Fluent method builders — required parameters are constructor arguments,
everything else is a chainable setter with typo protection
(
BadMethodCallExceptionfor unknown parameters). - Structured updates — a webhook payload becomes a typed object graph:
$tg->updates->message->chat->id,$message->entities[0]->type, … - Typed method results —
_result()gives you HTTP status, Telegramok, the decoded body and error helpers. - Uploads included — pass a
SplFileInfo, a stream or aCURLFileand the request switches tomultipart/form-dataautomatically. - No global state — a single
Telegramobject owns its Guzzle client, token, base URL and output format.
Requirements
| Requirement | Version |
|---|---|
| PHP | >= 8.2 |
| guzzlehttp/guzzle | ^7.8 |
| estaheri/json | ^1.0 |
ext-json |
enabled (default) |
Installation
composer require estaheri/easytel
Then load Composer's autoloader:
require_once __DIR__ . '/vendor/autoload.php';
Quick start
<?php use EasyTel\Telegram; use EasyTel\Types\InlineKeyboardButton; use EasyTel\Types\InlineKeyboardMarkup; require_once __DIR__ . '/vendor/autoload.php'; // The raw webhook body (or null when you instantiate the bot for a plain request) $updates = file_get_contents('php://input') ?: null; $tg = new Telegram(BOT_TOKEN, $updates); // Incoming update $message = $tg->updates?->message; $chat_id = $message?->chat->id; // Outgoing method if ($message?->text === '/start') { $tg->methods->sendMessage('Welcome!') ->chat_id($chat_id) ->reply_markup(InlineKeyboardMarkup::make( inline_keyboard: [[ InlineKeyboardButton::make(text: 'Open website', url: 'https://core.telegram.org/bots/api'), ]] )) ->_result(); }
Constructor
new Telegram( string $bot_token, // token from @BotFather ?string $updates = null, // raw webhook JSON (optional) string $botapi_url = 'https://api.telegram.org', string $request_method = 'POST', // POST or GET array $guzzle_client_options = [], // proxy, verify, timeout, ... int $output = Telegram::OUTPUT_OBJECT );
| Argument | Purpose |
|---|---|
$bot_token |
Bot token. Used to build https://api.telegram.org/bot<token>/ |
$updates |
Raw JSON body from the webhook. Parsed into EasyTel\Types\Update |
$botapi_url |
Point this at a local Bot API server if you use one |
$request_method |
POST (recommended) or GET; GET sends parameters in the query string |
$guzzle_client_options |
Any Guzzle request option: proxy, verify, timeout, connect_timeout, … |
$output |
Default format for Result::response() and Types output |
The public properties are:
$tg->methods; // EasyTel\Helper\Methods — all Bot API methods $tg->updates; // EasyTel\Types\Update|array|null — parsed webhook payload $tg->webhook; // EasyTel\Webhook — legacy helper: setWebhook/deleteWebhook/getWebhookInfo $tg->output; // int — the configured output format
Sending requests
Every Bot API method is available on $tg->methods with the same name as in the
official documentation (camelCase):
$tg->methods->sendMessage(...); $tg->methods->sendPhoto(...); $tg->methods->banChatMember(...); $tg->methods->getChatAdministrators(...);
Required and optional parameters
Parameters marked required in the Bot API documentation are constructor arguments; all optional ones are chainable setters. The setter name is exactly the Bot API parameter name, so the official docs apply one to one.
use EasyTel\Types\ReplyParameters; $tg->methods->sendMessage('Hello from EasyTel') // required: text ->chat_id($chat_id) // optional fluent setters ->message_thread_id($topic_id) ->parse_mode('HTML') ->disable_notification(true) ->reply_parameters(ReplyParameters::make( message_id: $message_id, chat_id: $chat_id, )) ->_result();
A setter that does not exist for the method throws
BadMethodCallException, so typos never reach Telegram:
$tg->methods->sendMessage('hi')->parse_mod('HTML'); // BadMethodCallException $tg->methods->sendMessage('hi')->chat_id(); // InvalidArgumentException
Fire and forget
_result() is optional. If you ignore the builder, the request is sent when the
object is destroyed:
// Both send a message, the second one simply ignores the response. $tg->methods->sendMessage('done')->chat_id($chat_id)->_result(); $tg->methods->sendMessage('done')->chat_id($chat_id);
Use _result() whenever you need to know whether the request worked.
Handling results
_result() returns an EasyTel\Handler\Result:
use EasyTel\Helper\Types; $result = $tg->methods->getMe()->_result(); if ($result->success && $result->ok) { // HTTP 2xx AND Telegram "ok": true $me = Types::make($result->response())->User(); echo "Logged in as @{$me->username}"; } else { $error = $result->success ? $result->response()->description // Telegram error (400, 403, 409, 429, ...) : $result->fail()->error; // transport error (DNS, timeout, TLS, ...) echo "Error: $error"; }
| Member | Meaning |
|---|---|
$result->success |
The HTTP request itself succeeded |
$result->ok |
The decoded body has "ok": true |
$result->response(?int $format = null) |
The full Telegram envelope ({"ok":…,"result":…}) |
$result->success() |
{code, header, size} or null |
$result->fail() |
{code, error} for transport errors, or null |
The bot token is never exposed in transport errors: messages are sanitized to
https://api.telegram.org/bot<token>/…, so they are safe to log.
Output formats
Result::response() and every _output() call accept one of:
Telegram::OUTPUT_OBJECT; // stdClass (default) Telegram::OUTPUT_ARRAY; // nested arrays Telegram::OUTPUT_JSON; // JSON string
$tg = new Telegram(BOT_TOKEN, $updates, output: Telegram::OUTPUT_ARRAY); $result = $tg->methods->getMe()->_result(); $id = $result->response()['result']['id']; // array, because OUTPUT_ARRAY was set // Or ask for another format just for this call: $json = $result->response(Telegram::OUTPUT_JSON);
A body that is not JSON (for example a gateway HTML error page) is returned
as-is instead of being silently converted to false.
Receiving updates
Telegram offers two ways to receive updates: a webhook (recommended) or long polling.
Webhook
Point Telegram at a public HTTPS endpoint that runs your handler:
<?php require_once __DIR__ . '/vendor/autoload.php'; $body = file_get_contents('php://input'); // Reject anything that is not your bot's webhook traffic. if ($_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] !== WEBHOOK_SECRET) { http_response_code(403); exit; } $tg = new EasyTel\Telegram(BOT_TOKEN, $body); $tg->updates?->message?->text; // typed update graph
Register the webhook:
$tg = new EasyTel\Telegram(BOT_TOKEN); $tg->methods->setWebhook('https://example.com/telegram.php') ->secret_token(WEBHOOK_SECRET) // sent as X-Telegram-Bot-Api-Secret-Token ->max_connections(40) ->drop_pending_updates(true) ->_result();
Inspect or remove it:
$info = $tg->methods->getWebhookInfo()->_result(); $info = EasyTel\Helper\Types::make($info->response())->WebhookInfo(); $tg->methods->deleteWebhook()->drop_pending_updates(true)->_result();
$tg->webhook->setWebhook(...), deleteWebhook(...) and getWebhookInfo() are
kept as convenience aliases for the same three methods.
Reading an update
$tg->updates is a fully typed object graph. Only the fields present in the
payload are initialized, so use isset() or ?->:
$update = $tg->updates; // EasyTel\Types\Update $message = $update?->message; // EasyTel\Types\Message $update_id = $update?->update_id; $chat_id = $message?->chat->id; $user_id = $message?->from->id; $text = $message?->text; $username = $message?->from->username ?? $message?->from->first_name; $timestamp = $message?->date; // reply / entities $replied_text = $message?->reply_to_message->text; $entity = $message?->entities[0] ?? null; // EasyTel\Types\MessageEntity $entity_type = $entity?->type; // "bold", "mention", ... // media $photo = $message?->photo; // array of EasyTel\Types\PhotoSize $file_id = $photo[0]->file_id ?? null; // callback queries, inline queries, chat member changes, ... $callback = $update?->callback_query; $callback_id = $callback?->id; $data = $callback?->data;
getUpdates, getChatAdministrators, getMyCommands and other list-returning
methods resolve to arrays of typed objects:
$users = Types::make($result->response())->ChatMember(); // EasyTel\Types\ChatMember[]
Long polling with getUpdates
$tg = new EasyTel\Telegram(BOT_TOKEN); $tg->methods->deleteWebhook()->_result(); // polling requires no webhook $offset = 0; while (true) { $result = $tg->methods->getUpdates() ->offset($offset) ->limit(100) ->timeout(30) // long polling ->allowed_updates(json_encode(['message', 'callback_query'])) ->_result(); if (!$result->success || !$result->ok) { sleep(3); continue; } /** @var EasyTel\Types\Update[] $updates */ $updates = EasyTel\Helper\Types::make($result->response())->Update(); foreach ($updates as $update) { $offset = $update->update_id + 1; echo $update->message?->text ?? '', PHP_EOL; } }
Working with types
All Bot API objects are classes under EasyTel\Types. They are plain data
objects: public typed properties, a make() factory and chainable setters.
Building objects
use EasyTel\Types\ReplyParameters; // named arguments (recommended) $reply = ReplyParameters::make( message_id: 42, chat_id: $chat_id, allow_sending_without_reply: true, ); // fluent setters $reply = ReplyParameters::make()->message_id(42)->chat_id($chat_id); // create from raw Telegram JSON (or from an array) $user = EasyTel\Helper\Types::make($result->response())->User();
EasyTel\Helper\Types is the inbound factory: Types::make($payload)->User(),
->Message(), ->Chat(), … It unwraps the {"ok":true,"result":…} envelope
automatically and supports all 425 types (with @method annotations for
autocomplete).
Arrays of objects
Array fields are hydrated into arrays of typed objects, including nested arrays (such as keyboard rows):
$message->entities[0] // EasyTel\Types\MessageEntity $message->photo[0] // EasyTel\Types\PhotoSize $message->reply_markup->inline_keyboard[0][0] // EasyTel\Types\InlineKeyboardButton $message->new_chat_members[0] // EasyTel\Types\User // getChat() returns the full chat info $chat = EasyTel\Helper\Types::make($tg->methods->getChat($chat_id)->_result()->response())->ChatFullInfo(); $chat->available_reactions[0] // EasyTel\Types\ReactionTypeEmoji
“One of” types (union bases)
Some fields can be one of several objects, e.g. forward_origin is a
MessageOrigin (User, HiddenUser, Chat or Channel). These are generated
as a base class with one property per variant; the matching variant is a nested
property:
$origin = $tg->updates->message->forward_origin; // EasyTel\Types\MessageOrigin $channel = $origin->messageoriginchannel; // EasyTel\Types\MessageOriginChannel $title = $channel->chat->title;
Other examples: TransactionPartner ($tx->source->transactionpartneruser),
ChatMember ($update->my_chat_member->new_chat_member->chatmemberadministrator),
BackgroundType, ReactionType, StoryAreaType, WidgetQueryType.
When a field is a real PHP union (for example InputRichMessageMedia::$media),
the concrete class is chosen from the payload's type. RichText — documented
by Telegram as “a String for plain text, an Array of RichText, or one of the
following types” — accepts all three forms.
Sending files
Pass a SplFileInfo, an open stream or a CURLFile and the library switches the
request to multipart/form-data:
// upload from disk $tg->methods->sendPhoto(new \SplFileInfo('/path/to/photo.jpg')) ->chat_id($chat_id) ->caption('Uploaded with EasyTel') ->_result(); // upload from an open stream $tg->methods->sendDocument(fopen('/path/to/file.pdf', 'rb')) ->chat_id($chat_id); // re-send a file that already exists on Telegram's servers $tg->methods->sendPhoto($file_id)->chat_id($chat_id);
Plain strings are never treated as local paths — they are forwarded to
Telegram as a file_id or an HTTP URL, exactly as the Bot API expects.
Cookbook
Inline keyboard
use EasyTel\Types\InlineKeyboardButton; use EasyTel\Types\InlineKeyboardMarkup; $keyboard = InlineKeyboardMarkup::make(inline_keyboard: [ [ InlineKeyboardButton::make(text: 'Yes', callback_data: 'answer:yes'), InlineKeyboardButton::make(text: 'No', callback_data: 'answer:no'), ], [ InlineKeyboardButton::make(text: 'Documentation', url: 'https://core.telegram.org/bots/api'), ], ]); $tg->methods->sendMessage('Continue?') ->chat_id($chat_id) ->reply_markup($keyboard) ->_result();
Answering a callback query
$callback = $tg->updates?->callback_query; if ($callback !== null) { $tg->methods->answerCallbackQuery($callback->id) ->text('Saved!') ->show_alert(true) // or false for a toast ->_result(); // the message the button belongs to $message_id = $callback->message?->message_id; }
Chat permissions
use EasyTel\Types\ChatPermissions; $tg->methods->restrictChatMember( $chat_id, $user_id, ChatPermissions::make(can_send_messages: false) )->until_date(time() + 3600);
Rich messages
use EasyTel\Types\InputRichBlockParagraph; use EasyTel\Types\InputRichMessage; use EasyTel\Types\RichText; use EasyTel\Types\RichTextBold; $tg->methods->sendRichMessage( InputRichMessage::make(blocks: [ InputRichBlockParagraph::make(type: 'paragraph', text: 'Plain text works too'), InputRichBlockParagraph::make( type: 'paragraph', text: RichText::make( richtextbold: RichTextBold::make(type: 'bold', text: 'and nested formatting') ) ), ]) )->chat_id($chat_id)->_result();
Advanced
Local Bot API server
$tg = new EasyTel\Telegram( BOT_TOKEN, $updates, botapi_url: 'http://localhost:8081' );
The request URL becomes http://localhost:8081/bot<token>/<method>.
Proxy and other Guzzle options
$tg = new EasyTel\Telegram(BOT_TOKEN, $updates, guzzle_client_options: [ 'proxy' => 'socks5://127.0.0.1:10808', 'verify' => false, // do not do this in production 'timeout' => 30, ]);
GET instead of POST
$tg = new EasyTel\Telegram(BOT_TOKEN, $updates, request_method: 'GET');
With GET, parameters are sent in the query string. POST (the default) is
recommended because Telegram supports larger payloads that way and uploads
require multipart/form-data.
Project structure
src/
├── Telegram.php entry point: token, Guzzle client, updates, methods
├── Webhook.php setWebhook / deleteWebhook / getWebhookInfo helper
├── Handler/
│ ├── Request.php transport: form / query / multipart + error mapping
│ └── Result.php success, ok, response(), fail()
├── Helper/
│ ├── Methods.php facade listing all 193 methods
│ ├── Types.php inbound factory: Types::make($json)->User()
│ └── Statics.php hydration and output formatting
├── Methods/ 193 fluent request builders
└── Types/ 425 data objects
test/
├── test.php webhook handler example
├── test2.php getMe + sendMessage smoke test
└── config.php reads credentials from the environment
Testing
The bundled scripts read credentials from environment variables — nothing is hard-coded:
export EASYTEL_BOT_TOKEN="123456789:AA..." export EASYTEL_TEST_USER_ID="123456789" # your own user id export EASYTEL_PROXY="socks5://127.0.0.1:10808" # optional php test/test2.php
test/test2.php calls getMe, hydrates the returned User object and (when
EASYTEL_TEST_USER_ID is set) sends a message to you. test/test.php is a
complete webhook handler showing keyboards, replies, callback queries and photo
forwarding.
Notes on generated code
src/Types and src/Methods are generated from the official Bot API
documentation (including the phpdoc text and the required/optional split). They
are kept in sync with the documentation; do not edit them by hand — put
changes in the generator templates so a regeneration does not overwrite them.
Shared behaviour lives in the hand-written classes — Telegram.php,
Handler/Request.php (transport), Handler/Result.php (response),
Helper/Statics.php (hydration/output) and Helper/Types.php (inbound factory).
Contributing
- Fork the repository and create a branch.
- Keep the code style of the surrounding files (PSR-12, typed properties, no
strict_typescurrently). - Run
php -lon changed files andphp test/test2.phpwith your own bot. - Open a pull request describing the change and, for API updates, the Bot API changelog entry it corresponds to.
Bug reports and feature requests are welcome in the issue tracker.
License
EasyTel is released under the MIT license.
Copyright (c) 2023 Esmaeil Taheri.