Telegram Bot API PHP SDK

https://github.com/irazasyed/telegram-bot-sdk
Admin
Telegram Bot PHP SDK allows developers to easily create Telegram Bots using PHP, with out-of-the-box...
Tokens:147,572
Snippets:1,114
Trust Score:9.7
License:BSD-3-Clause
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### StartCommand example with replyWithMessage

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Command.md

A concrete command subclass that greets the user. It uses the 'start' name with aliases 'go' and 'begin', a pattern '{name}', and auto-fills chat_id via the Answerable trait.

```php
class StartCommand extends Command
{
    protected $name = 'start';
    protected $aliases = ['go', 'begin'];
    protected $description = 'Greet the user';
    protected $pattern = '{name}';

    public function handle()
    {
        $name = $this->argument('name', 'friend');
        $this->replyWithMessage(['text' => "Hello, {$name}!"]);   // chat_id auto-filled
    }
}
```

--------------------------------

### Artisan webhook command usage examples

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Laravel.md

Shows command-line invocations for setting up, removing, and getting info about webhooks, including using a specific bot or all bots.

```bash
php artisan telegram:webhook --setup              # default bot
php artisan telegram:webhook mybot --setup --remove
php artisan telegram:webhook --info --all
```

--------------------------------

### Usage example: subscribing to events

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Events.md

Shows how to create an Api instance, subscribe to 'update' and 'update.message' events, and set a custom event dispatcher. The example uses the Emitter class or EventDispatcherFactory::create().

```php
use Telegram\Bot\Api;
use Telegram\Bot\Events\UpdateEvent;
use Telegram\Bot\Events\UpdateWasReceived;

$telegram = new Api('TOKEN');

$telegram->on('update', function (UpdateEvent $event) {
    echo 'Update ID: '.$event->update->updateId;
});

$telegram->on('update.message', function (UpdateEvent $event) {
    $event->telegram->sendMessage([
        'chat_id' => $event->update->getChat()->id,
        'text'    => 'Got your message!',
    ]);
});

// custom dispatcher
use Telegram\Bot\Events\Emitter;
$telegram->useEventDispatcher(new Emitter);
// or EventDispatcherFactory::create()
```

--------------------------------

### Usage example

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Events.md

Example of using the event system to subscribe to update events and send messages, as well as disabling events for polling.

```APIDOC
## Usage Example

### Description
This example demonstrates how to subscribe to events using the `on` method, access event data, and disable event dispatch for polling loops.

### Example Code
```php
use Telegram\Bot\Api;
use Telegram\Bot\Events\UpdateEvent;
use Telegram\Bot\Events\UpdateWasReceived;

$telegram = new Api('TOKEN');

$telegram->on('update', function (UpdateEvent $event) {
    echo 'Update ID: '.$event->update->updateId;
});

$telegram->on('update.message', function (UpdateEvent $event) {
    $event->telegram->sendMessage([
        'chat_id' => $event->update->getChat()->id,
        'text'    => 'Got your message!',
    ]);
});

// custom dispatcher
use Telegram\Bot\Events\Emitter;
$telegram->useEventDispatcher(new Emitter);
// or EventDispatcherFactory::create()
```

### Disabling Events for Polling
```php
$updates = $telegram->getUpdates([], false);   // no events dispatched
$update  = $telegram->getWebhookUpdate(false); // no events dispatched
```
```

--------------------------------

### Inline keyboard usage example

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Keyboard.md

Complete example of sending a message with an inline keyboard containing like/dislike buttons and a GitHub link. The reply_markup is stringified by Http::replyMarkupToString().

```php
use Telegram\Bot\Api;
use Telegram\Bot\Keyboard\Keyboard;

$telegram = new Api('TOKEN');

$replyMarkup = Keyboard::make()
    ->inline()
    ->row([
        Keyboard::inlineButton(['text' => '👍', 'callback_data' => 'like']),
        Keyboard::inlineButton(['text' => '👎', 'callback_data' => 'dislike']),
    ])
    ->row([
        Keyboard::inlineButton(['text' => 'GitHub', 'url' => 'https://github.com']),
    ]);

$telegram->sendMessage([
    'chat_id'     => 123,
    'text'        => 'Rate this bot:',
    'reply_markup' => $replyMarkup,     // stringified by Http::replyMarkupToString()
]);
```

--------------------------------

### addCommands() usage examples

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/CommandBus.md

Example calls to addCommands(). The first shows a conditional class-string; the second simpler form registers two command classes.

```php
$bus->addCommands([HelpCommand::class, '/path/to/MyCommand.php' === '' ? null : MyCommand::class]);
// simpler:
$bus->addCommands([
    \App\Commands\StartCommand::class,
    \App\Commands\StopCommand::class,
]);
```

--------------------------------

### downloadFile usage example

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Api.md

Downloads a file using a raw file id to a directory path.

```php
$localPath = $telegram->downloadFile('AgAD...fileId', '/var/www/downloads/');
```

--------------------------------

### Magic __call method

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/BaseObject.md

Handles magic get* method calls. Methods not starting with 'get' return false; otherwise it calls getPropertyValue with the rest of the method name.

```php
public function __call($method, $parameters)
```

--------------------------------

### Example relations() method from Chat.php

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/BaseObject.md

Shows how subclasses declare relations. Keys map to FQCN strings for single objects or list of class-strings for collections.

```php
// from src/Objects/Chat.php
public function relations(): array
{
    return [
        'photo' => InputMedia::class,
        'pinned_message' => Message::class,
        'permissions' => ChatPermissions::class,
        'location' => ChatLocation::class,
    ];
}
```

--------------------------------

### Usage Example: Creating a Message Object

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/BaseObject.md

Demonstrates how to instantiate a Message object with raw data and access its properties and relations.

```APIDOC
## Usage Example: Creating a Message Object

### Description
Shows how to create a Message object from an array and access its properties, including nested objects and immutability.

### Code Example
```php
use Telegram\Bot\Objects\Message;

$message = new Message([
    'ok' => true,
    'result' => [
        'message_id' => 42,
        'text' => 'hi',
        'from' => ['id' => 7, 'first_name' => 'A'],
    ],
]);

echo $message->messageId;      // 42     (result unwrapped by getRawResult)
echo $message->from->id;       // 7      (User object via relation)
echo $message->from->firstName;// 7      (property is snake_cased before lookup)
$message->text = 'x';          // InvalidArgumentException: immutable
```
```

--------------------------------

### Reply keyboard with remove example

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Keyboard.md

Shows creating a reply keyboard with a resize option and a contact request button, then sending a message with it and later removing it with Keyboard::remove().

```php
use Telegram\Bot\Keyboard\Keyboard;

$markup = Keyboard::make()->setResizeKeyboard(true)->row([
    Keyboard::button('Start'),
    Keyboard::button(['text' => '📞', 'request_contact' => true]),
]);

$telegram->sendMessage(['chat_id' => 123, 'text' => 'Pick', 'reply_markup' => $markup]);

// later, remove the keyboard:
$telegram->sendMessage(['chat_id' => 123, 'text' => 'Done', 'reply_markup' => Keyboard::remove()]);
```

--------------------------------

### Usage example: fetching updates and accessing properties

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/BaseObject.md

Shows how to instantiate the API, fetch updates, and access properties like updateId, message, chat, photo, and text using magic methods and relations.

```php
use Telegram\Bot\Api;
use Telegram\Bot\Objects\Update;

$telegram = new Api('TOKEN');
$updates  = $telegram->getUpdates();

foreach ($updates as $update) {
    /** @var Update $update */
    echo $update->updateId;                              // magic property (snake-cased)
    $message = $update->message;                         // hydrated Message object (relation)
    echo $message->getChat()->id;                        // nested Chat object
    $photo = $message->photo;                            // Collection of PhotoSize objects
    echo $message->getText();                            // magic get* call -> text
}
```

--------------------------------

### Api::manager() usage example

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Api.md

Creates a BotsManager with a default bot and retrieves a bot instance by name.

```php
$manager = Api::manager([
    'default' => 'mybot',
    'bots' => ['mybot' => ['token' => '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11']],
]);
$mybot = $manager->bot('mybot');
```

--------------------------------

### getFile

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/endpoints.md

Gets information about a file.

```APIDOC
## GET getFile

### Description
Gets information about a file.

### Method
GET

### Endpoint
getFile

### Parameters
#### Path Parameters
- **file_id** - Required - File identifier

### Response
#### Success Response (200)
- **File** - File object

```

--------------------------------

### Send primitives: get, post, uploadFile

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Methods.md

The three send primitives: get sends params as query string, post wraps params as form_params or multipart, uploadFile handles file uploads and throws CouldNotUploadInputFile::missingParam when the field is absent.

```php
protected function get(string $endpoint, array $params = []): TelegramResponse
// GET — params sent as query string; reply_markup stringified first
```

```php
public function post(string $endpoint, array $params = [], bool $fileUpload = false): TelegramResponse
// POST — params wrapped as Guzzle 'form_params'; with $fileUpload=true wrapped as 'multipart'
// Normalizes params: multipart values pass through prepareMultipartParams(); form_params pass replyMarkupToString()
```

```php
protected function uploadFile(string $endpoint, array $params, string $inputFileField): TelegramResponse
// POST + multipart — throws CouldNotUploadInputFile::missingParam when the field is absent;
// if the field is a file_id (Validator::isFileId) it falls back to a plain post() instead of uploading
```

--------------------------------

### getMyCommands

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/endpoints.md

Gets the list of bot commands.

```APIDOC
## GET getMyCommands

### Description
Gets the list of bot commands.

### Method
GET

### Endpoint
getMyCommands

### Parameters
No parameters.

### Response
#### Success Response (200)
- **array** (BotCommand[]) - List of bot commands

```

--------------------------------

### Telegram facade usage examples

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Laravel.md

Shows how to use the Telegram facade to send messages via the default bot or a named bot, and to fetch updates.

```php
use Telegram\Bot\Laravel\Facades\Telegram;

Telegram::sendMessage(['chat_id' => 123, 'text' => 'Hello!']);   // default bot
Telegram::bot('mybot')->sendMessage(['chat_id' => 123, 'text' => 'Hi!']);
Telegram::getUpdates();
```

--------------------------------

### Full webhook flow example

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Methods-Update.md

Complete webhook flow: initializes the API, sets the webhook URL, and in the handler retrieves the update, checks if it is a message, and echoes back the message text.

```php
use Telegram\Bot\Api;
use Telegram\Bot\Exceptions\TelegramSDKException;

$telegram = new Api('TOKEN');

try {
    $telegram->setWebhook(['url' => 'https://example.com/hook']);
} catch (TelegramSDKException $e) {
    // handle validation failure
}

// in the webhook handler:
$update = $telegram->getWebhookUpdate();
if ($update->isType('message')) {
    $telegram->sendMessage(['chat_id' => $update->getChat()->id, 'text' => 'Echo: '.$update->message->text]);
}
```

--------------------------------

### BotsManager config array example (config/telegram.php)

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/configuration.md

Example Laravel config/telegram.php array showing how to define a bot with token and commands, plus global commands, command groups, and shared commands. The 'admin' group is referenced by name in the bot's commands list and expands to '/staff' and PingCommand. The 'status' shared command maps to StatusCommand and can be used by any bot or group.

```php
// config/telegram.php
return [
    'default' => 'mybot',
    'bots' => [
        'mybot' => [
            'token' => env('TELEGRAM_BOT_TOKEN', 'YOUR-BOT-TOKEN'),
            'commands' => [
                'admin',                                // group name
                \App\Commands\StartCommand::class,      // FQCN
            ],
        ],
    ],
    'commands' => [\Telegram\Bot\Commands\HelpCommand::class],
    'command_groups' => [
        'admin' => ['/staff', \App\Commands\PingCommand::class],
    ],
    'shared_commands' => [
        'status' => \App\Commands\StatusCommand::class,
    ],
];
```

--------------------------------

### Retrieve and use a bot instance

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/BotsManager.md

Gets the 'primary' bot and sends a message, then retrieves the default bot. The bot() method builds the instance on first use.

```php
$api = $manager->bot('primary');
$api->sendMessage(['chat_id' => 1, 'text' => 'hi']);

$manager->bot();                  // default bot
```

--------------------------------

### Create new sticker set with InputFile

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Methods-Stickers.md

Example of calling createNewStickerSet with an InputFile sticker. The sticker is attached using attach:// and the request is sent as multipart. Required parameters: user_id, name, title, stickers (1-50). Optional: sticker_type, needs_repainting.

```php
use Telegram\Bot\FileUpload\InputFile;

$telegram->createNewStickerSet([
    'user_id' => 123,
    'name'    => 'animals_by_example_bot',
    'title'   => 'Animals',
    'stickers' => [
        [
            'sticker'    => InputFile::create('/tmp/panda.webp'),
            'format'     => 'static',
            'emoji_list' => ['🐼'],
            'keywords'   => ['panda'],
        ],
    ],
    'sticker_type'     => 'regular',
    'needs_repainting' => false,
]);
```

--------------------------------

### Creating a TelegramRequest with timeouts

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/TelegramRequest.md

Shows how to instantiate a TelegramRequest with an access token, HTTP method, endpoint, and params, then set timeouts. The example uses the 'sendMessage' endpoint and demonstrates calling getMethod() which returns 'POST'.

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

use Telegram\Bot\TelegramRequest;

$request = (new TelegramRequest('123456:ABC', 'POST', 'sendMessage', ['chat_id' => 1, 'text' => 'hi']))
    ->setTimeOut(60)
    ->setConnectTimeOut(10);

$request->getMethod();   // "POST"
```

--------------------------------

### Subscribe to update.message event with on()

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Api.md

Example of using the on() method to subscribe to the 'update.message' event. The callback is fired per incoming message update.

```php
$telegram->on('update.message', function (UpdateEvent $event) {
    // fired per incoming message update
});
```

--------------------------------

### Usage Example: Accessing Update and Message Objects

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/BaseObject.md

Demonstrates how to use the Telegram Bot SDK to fetch updates and access object properties and relations.

```APIDOC
## Usage Example: Accessing Update and Message Objects

### Description
Shows how to retrieve updates and access properties and relations of Update and Message objects.

### Code Example
```php
use Telegram\Bot\Api;
use Telegram\Bot\Objects\Update;

$telegram = new Api('TOKEN');
$updates  = $telegram->getUpdates();

foreach ($updates as $update) {
    /** @var Update $update */
    echo $update->updateId;                              // magic property (snake-cased)
    $message = $update->message;                         // hydrated Message object (relation)
    echo $message->getChat()->id;                        // nested Chat object
    $photo = $message->photo;                            // Collection of PhotoSize objects
    echo $message->getText();                            // magic get* call -> text
}
```
```

--------------------------------

### Get file URL

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/TelegramClient.md

Builds the file-download URL in the format {BASE_BOT_URL}/file/bot{TOKEN}/{FILE_PATH}. The BASE_BOT_URL placeholder is the base URL with /bot stripped.

```php
$url = $client->getFileUrl('photos/file_1.jpg', $request);
// https://api.telegram.org/file/botTOKEN/photos/file_1.jpg
```

--------------------------------

### getMyCommands(array $params = []): array

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Methods-Misc.md

Gets the current list of bot commands for the given scope and user language. Supports optional scope and language_code. Returns an array of BotCommand objects.

```APIDOC
## getMyCommands

### Description
Gets the current list of bot commands for the given scope and user language.

### Method
GET

### Endpoint
getMyCommands

### Parameters
#### Optional Parameters
- **scope** (object) - Optional - BotCommandScope-shaped data
- **language_code** (string) - Optional - Two-letter ISO 639-1 language code

### Request Example
```php
$commands = $telegram->getMyCommands();
```

### Response
#### Success Response (200)
Returns an array of `BotCommand` objects (fields: `command`, `description`).
```

--------------------------------

### Entities Helper API and Usage

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Helpers.md

Shows the public API of the Entities helper class. Use format() to start, withEntities() to attach raw MessageEntity arrays, then convert to Markdown or HTML.

```php
public function __construct(private string $text)

public static function format(string $text): self
public function withEntities(array $entities): self   // entities from $message->entities (raw arrays)
public function toMarkdown(): string
public function toHTML(): string
```

```php
use Telegram\Bot\Helpers\Entities;

$text     = $message->text;              // "Hello *world*"
$entities = $message->entities->all();   // MessageEntity[] → arrays

echo Entities::format($text)->withEntities($entities)->toMarkdown();
echo Entities::format($text)->withEntities($entities)->toHTML();
```

--------------------------------

### EventDispatcherFactory::create()

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Events.md

Creates an event dispatcher instance based on the availability of league/event classes. Returns a LeagueEventDispatcher if league/event v3 is installed, otherwise returns an Emitter.

```APIDOC
## EventDispatcherFactory::create()

### Description
Creates an event dispatcher instance based on the availability of league/event classes. Returns a LeagueEventDispatcher if league/event v3 is installed, otherwise returns an Emitter.

### Method
`create`

### Signature
```php
public static function create(): EventDispatcherListenerContract
```

### Returns
- **EventDispatcherListenerContract** - The event dispatcher instance.

### Example
```php
$dispatcher = EventDispatcherFactory::create();
```
```

--------------------------------

### Using `Actions::TYPING` with `sendChatAction` and validating actions

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Helpers.md

Usage example sending a chat action and validating an action. `sendChatAction` demonstrates passing the `action` constant; the `try` block shows the exception thrown by `isActionValid` for an invalid value.

```php
use Telegram\Bot\Actions;
use Telegram\Bot\Api;

$telegram = new Api('TOKEN');
$telegram->sendChatAction(['chat_id' => 123, 'action' => Actions::TYPING]);

try {
    Actions::isActionValid('not_a_real_action');
} catch (\Telegram\Bot\Exceptions\TelegramSDKException $e) {
    // "Invalid Action! Accepted value: …"
}
```

--------------------------------

### Usage example: creating a Message object and accessing properties

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/BaseObject.md

Demonstrates creating a Message object with an array, accessing properties like messageId, from->id, from->firstName, and shows that setting a property throws an InvalidArgumentException because objects are immutable.

```php
use Telegram\Bot\Objects\Message;

$message = new Message([
    'ok' => true,
    'result' => [
        'message_id' => 42,
        'text' => 'hi',
        'from' => ['id' => 7, 'first_name' => 'A'],
    ],
]);

echo $message->messageId;      // 42     (result unwrapped by getRawResult)
echo $message->from->id;       // 7      (User object via relation)
echo $message->from->firstName;// 7      (property is snake_cased before lookup)
$message->text = 'x';          // InvalidArgumentException: immutable
```

--------------------------------

### Example of validateMethod() throwing exception for DELETE

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/TelegramRequest.md

Shows a try-catch block that calls validateMethod() with method 'DELETE', which is invalid and triggers the exception with message 'Invalid HTTP method specified. Must be GET or POST'.

```php
try {
    (new TelegramRequest('T'))->setMethod('DELETE')->validateMethod();
} catch (\Telegram\Bot\Exceptions\TelegramSDKException $e) {
    // "Invalid HTTP method specified. Must be GET or POST"
}
```

--------------------------------

### Building a reply keyboard with button() and row()

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Keyboard.md

Demonstrates creating a reply keyboard with two rows: one with simple text buttons and one with a request_contact button.

```php
$keyboard = Keyboard::make()
    ->row([Keyboard::button('Yes'), Keyboard::button('No')])
    ->row([Keyboard::button(['text' => 'Send contact', 'request_contact' => true])]);
```

--------------------------------

### Basic Api instantiation

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Api.md

Creates a new Api instance with a bot token. The token is passed directly as the first argument.

```php
use Telegram\Bot\Api;

$telegram = new Api('123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11');
```

--------------------------------

### restrictChatMember example

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Methods-Chat.md

Restricts a member's permissions in a chat. Required: chat_id, user_id, and permissions array. Optional: until_date and use_independent_chat_permissions. This example disables sending messages and media.

```php
$telegram->restrictChatMember([
    'chat_id' => 123,
    'user_id' => 999,
    'permissions' => ['can_send_messages' => false, 'can_send_media_messages' => false],
]);
```

--------------------------------

### banChatMember example

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Methods-Chat.md

Bans a user from a chat. Required parameters: chat_id and user_id. Optional: until_date and revoke_messages. This example bans user 999 from @mychannel for one hour and revokes messages.

```php
$telegram->banChatMember([
    'chat_id'        => '@mychannel',
    'user_id'        => 999,
    'until_date'     => time() + 3600,
    'revoke_messages' => true,
]);
```

--------------------------------

### GET /bot{accessToken}/{endpoint}

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/endpoints.md

HTTP GET request to the Telegram Bot API. Used by methods that retrieve data without a request body, and as a fallback for file-id parameters in uploads.

```APIDOC
## GET /bot{accessToken}/{endpoint}

### Description
Sends a GET request to the Telegram Bot API. Used by methods that retrieve data without a request body, and as a fallback for file-id parameters in uploads.

### Method
GET

### Endpoint
`{baseBotUrl}{accessToken}/{endpoint}`

### Parameters
#### Path Parameters
- **accessToken** (string) - Required - The bot access token embedded in the URL path.
- **endpoint** (string) - Required - The specific Telegram Bot API method endpoint.

#### Query Parameters
- **params** (object) - Optional - Query string parameters for the request.

### Response
#### Success Response (200)
- **result** (object) - The response payload from the Telegram API.

#### Response Example
{
  "ok": true,
  "result": {}
}
```

--------------------------------

### Create invite link and approve join request

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Methods-Chat.md

Creates a chat invite link with a member limit of 5 and prints the invite link. Then approves a join request for a user. Requires chat_id and user_id for approval.

```php
$link = $telegram->createChatInviteLink(['chat_id' => 123, 'member_limit' => 5]);
echo $link->inviteLink;                     // t.me/+abc...
$telegram->approveChatJoinRequest(['chat_id' => 123, 'user_id' => 999]);
```

--------------------------------

### GET deleteWebhook

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/endpoints.md

Deletes the webhook.

```APIDOC
## GET deleteWebhook

### Description
Removes the webhook integration.

### Method
GET

### Endpoint
deleteWebhook

### Parameters
None

### Response
#### Success Response (200)
- **result** (bool) - True on success

#### Response Example
{"ok": true, "result": true}
```

--------------------------------

### GET leaveChat

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Methods-Chat.md

Leaves a chat.

```APIDOC
## GET leaveChat

### Description
Leaves a chat.

### Method
GET

### Endpoint
leaveChat

### Parameters
#### Path Parameters
- **chat_id** (integer or string) - Required - Unique identifier for the target chat or username of the target channel (in the format @channelusername)

### Response
#### Success Response (200)
- Returns true on success.
```

--------------------------------

### InputFile::create

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/InputFile.md

Static factory method to create an InputFile instance from various file sources.

```APIDOC
## InputFile::create

### Description
Creates a new InputFile instance from a local path, remote URL, resource, or stream. Optionally accepts an explicit filename.

### Method
static

### Signature
```php
public static function create(mixed $file = null, ?string $filename = null): self
```

### Parameters
- **$file** (string | resource | StreamInterface | null) - Optional - Local path, remote URL, resource, or stream.
- **$filename** (?string) - Optional - Explicit filename (required for resources/streams without URI metadata).

### Return Value
- **self** - A new InputFile instance.

### Example
```php
$file = InputFile::create('/tmp/photo.png');
$file = InputFile::create('https://example.com/photo.png', 'photo.png');
```
```

--------------------------------

### GET unbanChatMember

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/endpoints.md

Unbans a chat member.

```APIDOC
## GET unbanChatMember

### Description
Unbans a user from a chat.

### Method
GET

### Endpoint
unbanChatMember

### Parameters
#### Query Parameters
- **chat_id** (integer/string) - Required - Chat identifier
- **user_id** (integer) - Required - User identifier

### Response
#### Success Response (200)
- **result** (bool) - True on success

#### Response Example
{"ok": true, "result": true}
```

--------------------------------

### GET banChatMember

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/endpoints.md

Bans a chat member.

```APIDOC
## GET banChatMember

### Description
Bans a user from a chat.

### Method
GET

### Endpoint
banChatMember

### Parameters
#### Query Parameters
- **chat_id** (integer/string) - Required - Chat identifier
- **user_id** (integer) - Required - User identifier

### Response
#### Success Response (200)
- **result** (bool) - True on success

#### Response Example
{"ok": true, "result": true}
```

--------------------------------

### GET kickChatMember

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/endpoints.md

Kicks a chat member.

```APIDOC
## GET kickChatMember

### Description
Kicks a user from a chat.

### Method
GET

### Endpoint
kickChatMember

### Parameters
#### Query Parameters
- **chat_id** (integer/string) - Required - Chat identifier
- **user_id** (integer) - Required - User identifier

### Response
#### Success Response (200)
- **result** (bool) - True on success

#### Response Example
{"ok": true, "result": true}
```

--------------------------------

### Instantiating Update and Message objects

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/BaseObject.md

Shows how to create Update and Message objects. Passing the full payload with 'result' key works, as does passing plain data.

```php
new Update($payload);                 // payload = ['ok' => true, 'result' => [...], 'update_id' => ...]
new Message(['message_id' => 1]);     // plain data too
```

--------------------------------

### GET getWebhookInfo

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/endpoints.md

Retrieves webhook information.

```APIDOC
## GET getWebhookInfo

### Description
Gets current webhook status.

### Method
GET

### Endpoint
getWebhookInfo

### Parameters
None

### Response
#### Success Response (200)
- **result** (WebhookInfo) - Webhook configuration info

#### Response Example
{"ok": true, "result": {"url": "https://example.com/hook", "has_custom_certificate": false, "pending_update_count": 0}}
```

--------------------------------

### GET getUpdates

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/endpoints.md

Fetches updates for the bot.

```APIDOC
## GET getUpdates

### Description
Retrieves a list of updates (messages, callbacks, etc.) for the bot.

### Method
GET

### Endpoint
getUpdates

### Parameters
None

### Response
#### Success Response (200)
- **result** (Update[]) - Array of Update objects

#### Response Example
{"ok": true, "result": [{"update_id": 123, "message": {}}]}
```

--------------------------------

### Constructor

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/BotsManager.md

Creates a new BotsManager instance with the given bot configuration array.

```APIDOC
## Constructor

### Description
Creates a new BotsManager instance with the given bot configuration array.

### Method
__construct

### Signature
```php
public function __construct(private array $config) {}
```

### Parameters
- **$config** (array) - Required - Bot configuration array. Same structure as `config/telegram.php`.

### Example
```php
use Telegram\Bot\BotsManager;

$manager = new BotsManager([
    'default' => 'primary',
    'bots' => [
        'primary' => ['token' => '111:AAA'],
        'backup'  => ['token' => '222:BBB'],
    ],
]);
```
```

--------------------------------

### getUserProfilePhotos

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/endpoints.md

Gets a user's profile photos.

```APIDOC
## GET getUserProfilePhotos

### Description
Gets a user's profile photos.

### Method
GET

### Endpoint
getUserProfilePhotos

### Parameters
#### Path Parameters
- **user_id** - Required - User identifier

### Response
#### Success Response (200)
- **UserProfilePhotos** - User profile photos

```

--------------------------------

### TelegramResponseException

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/errors.md

Documentation for the TelegramResponseException class, including its methods and usage examples.

```APIDOC
## TelegramResponseException

### Description
Exception thrown automatically by `TelegramClient::sendRequest()` whenever the Telegram API returns a payload with `ok: false`. It provides access to the error details from the API response.

### Methods

- `get($key, mixed $default = null)` — Returns a value from the response data (e.g., `description`, `error_code`, `parameters`).
- `getHttpStatusCode(): ?int` — Returns the HTTP status code from the underlying response.
- `getErrorType(): string` — Returns the error type from the response data (default `''`).
- `getRawResponse(): string` — Returns the raw JSON body of the response.
- `getResponseData(): array` — Returns the decoded response body as an array.
- `getResponse(): TelegramResponse` — Returns the full response entity.

### Usage Example

```php
use Telegram\Bot\Exceptions\TelegramResponseException;

try {
    $telegram->sendMessage(['chat_id' => 999999999, 'text' => 'hi']);
} catch (TelegramResponseException $e) {
    echo $e->getMessage();          // "Bad Request: chat not found"
    echo $e->getCode();             // 400
    echo $e->getHttpStatusCode();   // 400
    var_dump($e->getResponseData()); // ['ok' => false, 'error_code' => 400, 'description' => '...']
}
```

### Catching Order

Must be caught before the generic `TelegramSDKException`:

```php
try { ... }
catch (TelegramResponseException $e) { /* specific */ }
catch (TelegramSDKException $e)   { /* everything else */ }
```
```

--------------------------------

### Public getters and setters for Command properties

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Command.md

Lists the public getter and setter methods for name, aliases, description, arguments, and pattern. Each setter returns self for chaining.

```php
public function getName(): string
public function setName(string $name): self

public function getAliases(): array
public function setAliases(array|string $aliases): self

public function getDescription(): string
public function setDescription(string $description): self

public function getArguments(): array
public function setArguments(array $arguments): self

public function getPattern(): string
public function setPattern(string $pattern): self
```

--------------------------------

### Api::__construct

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Api.md

Creates a new Api instance with the given bot token and optional configuration. Throws TelegramSDKException if the token is missing or invalid.

```APIDOC
## Api::__construct

### Description
Creates a new Api instance for interacting with the Telegram Bot API. Accepts an optional token, async flag, custom HTTP client handler, and custom base bot URL.

### Method
Constructor

### Signature
```php
public function __construct(?string $token = null, bool $async = false, ?HttpClientInterface $httpClientHandler = null, ?string $baseBotUrl = null)
```

### Parameters
- **$token** (?string) - Optional - Bot access token. When null, falls back to `getenv('TELEGRAM_BOT_TOKEN')`.
- **$async** (bool) - Optional - If true, calls `setAsyncRequest(true)` — requests become non-blocking. Default: false.
- **$httpClientHandler** (?HttpClientInterface) - Optional - Custom HTTP client; null yields a `GuzzleHttpClient`. Default: null.
- **$baseBotUrl** (?string) - Optional - Custom base URL (local bot API server / proxy); null yields `https://api.telegram.org/bot`. Default: null.

### Throws
- **TelegramSDKException** - When the resolved token is `''` or `'0'` (see `validateAccessToken()`, src/Api.php:93 — message: `Required "token" not supplied in config and could not find fallback environment variable TELEGRAM_BOT_TOKEN`).

### Example
```php
use Telegram\Bot\Api;

$telegram = new Api('123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11');
```

### Example with named arguments
```php
use Telegram\Bot\Api;
use Telegram\Bot\Exceptions\TelegramSDKException;
use Telegram\Bot\HttpClients\GuzzleHttpClient;

try {
    $telegram = new Api(
        token: getenv('MY_BOT_TOKEN'),
        async: true,                                  // non-blocking requests
        httpClientHandler: new GuzzleHttpClient(),    // custom handler (default anyway)
        baseBotUrl: 'http://localhost:8081'           // local bot-api-server
    );
} catch (TelegramSDKException $e) {
    fwrite(STDERR, 'Missing token: '.$e->getMessage());
}
```
```

--------------------------------

### getGameHighScores

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Methods-EditMessage.md

Gets high scores for a game. Requires user_id. Returns GameHighScore[].

```APIDOC
## GET getGameHighScores

### Description
Gets high scores for a game. Requires user_id. Returns GameHighScore[].

### Method
GET

### Endpoint
getGameHighScores

### Parameters
#### Path Parameters
- **chat_id** (integer) - Optional - Unique identifier for the target chat.
- **message_id** (integer) - Optional - Identifier of the message.
- **inline_message_id** (string) - Optional - Identifier of the inline message.

#### Query Parameters
- **user_id** (integer) - Required - User identifier.

### Request Example
{
  "user_id": 123
}

### Response
#### Success Response (200)
Returns an array of GameHighScore objects, mapped via ->mapInto(GameHighScore::class). Each has relation user to User.

#### Response Example
[
  {
    "position": 1,
    "score": 500,
    "user": {
      "id": 123,
      "first_name": "John"
    }
  }
]
```

--------------------------------

### Setting a container and auto-resolving command dependencies

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Api.md

Shows how to set a PSR-11 compliant container (e.g., Laravel container) and then add a command whose constructor dependencies are auto-resolved from the container.

```php
use Telegram\Bot\Api;

Api::setContainer($app);   // e.g. Laravel container, PSR-11 compliant
if ($telegram->hasContainer()) {
    $telegram->addCommand(MyCommand::class); // ctor deps auto-resolved
}
```

--------------------------------

### Advanced Api instantiation with named arguments and error handling

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Api.md

Creates an Api instance using named arguments for async mode, a custom HTTP client, and a custom base URL. Catches TelegramSDKException if the token is missing.

```php
use Telegram\Bot\Api;
use Telegram\Bot\Exceptions\TelegramSDKException;
use Telegram\Bot\HttpClients\GuzzleHttpClient;

try {
    $telegram = new Api(
        token: getenv('MY_BOT_TOKEN'),
        async: true,                                  // non-blocking requests
        httpClientHandler: new GuzzleHttpClient(),    // custom handler (default anyway)
        baseBotUrl: 'http://localhost:8081'           // local bot-api-server
    );
} catch (TelegramSDKException $e) {
    fwrite(STDERR, 'Missing token: '.$e->getMessage());
}
```

--------------------------------

### Constructor signature

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/TelegramClient.md

Constructor accepts an optional HttpClientInterface and base URL. If null, defaults to GuzzleHttpClient and BASE_BOT_URL respectively.

```php
public function __construct(?HttpClientInterface $httpClientHandler = null, ?string $baseBotUrl = null)
```

--------------------------------

### getParams(): array

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/TelegramRequest.md

Returns the raw request parameters. Used by TelegramClient as the query array for GET requests.

```APIDOC
## getParams(): array

### Description
Returns the raw request parameters. Used by `TelegramClient` as the `query` array for GET requests.

### Method
GET (class method)

### Endpoint
N/A (SDK method)

### Parameters
None

### Request Example
N/A

### Response
#### Success Response
- **array** - The raw request parameters.

#### Response Example
```php
['chat_id' => 123, 'text' => 'Hello']
```
```

--------------------------------

### validateMethod(): void

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/TelegramRequest.md

Validates that the HTTP method is set and is either GET or POST. Throws exceptions for invalid methods.

```APIDOC
## validateMethod(): void

### Description
Validates that the HTTP method is set and is either GET or POST. Throws exceptions for invalid methods.

### Method
VALIDATE (PHP method)

### Signature
`public function validateMethod(): void`

### Throws
- **TelegramSDKException** - If the method is empty or '0', with message 'HTTP method not specified.'
- **TelegramSDKException** - If the method is not GET or POST, with message 'Invalid HTTP method specified. Must be GET or POST'

### Example
```php
try {
    (new TelegramRequest('T'))->setMethod('DELETE')->validateMethod();
} catch (\Telegram\Bot\Exceptions\TelegramSDKException $e) {
    // "Invalid HTTP method specified. Must be GET or POST"
}
```

```

--------------------------------

### InputFile constructor signature

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/InputFile.md

Constructor for InputFile, accepting an optional file source and filename.

```php
public function __construct(private mixed $file = null, private ?string $filename = null) {}
```

--------------------------------

### InputFile::createFromContents

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/InputFile.md

Static factory method to create an InputFile from raw string contents with a specified filename.

```APIDOC
## InputFile::createFromContents

### Description
Builds an InputFile from raw string contents with a forced filename.

### Method
static

### Signature
```php
public static function createFromContents(string $contents, string $filename): InputFile
```

### Parameters
- **$contents** (string) - Required - Raw file contents.
- **$filename** (string) - Required - Filename to associate with the contents.

### Return Value
- **InputFile** - A new InputFile instance with the given contents and filename.

### Example
```php
$file = InputFile::createFromContents('file contents', 'file.txt');
```
```

--------------------------------

### Using getResult() with sendChatAction

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/TelegramResponse.md

Example of using getResult() to check if a sendChatAction request succeeded. The result is true when the action was broadcast.

```php
$response = $telegram->post('sendChatAction', ['chat_id' => 1, 'action' => 'typing']);
if ($response->getResult() === true) {
    // action broadcast
}
```

--------------------------------

### Set game score and get high scores

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Methods-EditMessage.md

Sets a game score for a user and then retrieves the high scores for that user.

```php
$telegram->setGameScore(['user_id' => 123, 'score' => 500, 'chat_id' => 123, 'message_id' => 9]);
$scores = $telegram->getGameHighScores(['user_id' => 123]);
```

--------------------------------

### LeagueEventDispatcher class definition

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Events.md

Defines the LeagueEventDispatcher class that extends EventDispatcher and implements EventDispatcherListenerContract. Used when league/event v3 is installed.

```php
class LeagueEventDispatcher extends EventDispatcher implements EventDispatcherListenerContract {}
```

--------------------------------

### InputFile::create() static factory signature

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/InputFile.md

Static factory method to create an InputFile instance. Accepts a local path, remote URL, resource, or stream, with an optional explicit filename.

```php
public static function create(mixed $file = null, ?string $filename = null): self
```

--------------------------------

### getFile() and downloadFile() - Fetch file

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Methods-Misc.md

Retrieves file metadata by file_id, then downloads the actual file to a local path. The downloaded filename is the file_path basename appended to the target directory.

```php
$file = $telegram->getFile(['file_id' => 'AgAD...']);
$path = $telegram->downloadFile($file, '/tmp/');       // file_path basename appended
```

--------------------------------

### setMethod(?string $method): self

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/TelegramRequest.md

Sets the HTTP method, applying strtoupper() and validating that it is either GET or POST. Returns the current instance.

```APIDOC
## setMethod(?string $method): self

### Description
Sets the HTTP method for the request. The method is uppercased and must be either `GET` or `POST` to pass validation. Returns the current instance for chaining.

### Method
POST (class method)

### Endpoint
N/A (SDK method)

### Parameters
#### Request Body
- **method** (string|null) - Required - The HTTP method to set. Must be 'GET' or 'POST' after uppercasing.

### Request Example
```php
$request->setMethod('post');
```

### Response
#### Success Response
- **self** - The current TelegramRequest instance.

#### Response Example
```php
TelegramRequest instance
```
```

--------------------------------

### Constructor

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/TelegramResponse.md

Creates a new TelegramResponse instance from a TelegramRequest and a raw HTTP response or promise.

```APIDOC
## Constructor

### Description
Creates a new TelegramResponse instance. Accepts a TelegramRequest and a raw HTTP response (ResponseInterface) or a Guzzle promise (PromiseInterface). For synchronous responses, it stores the HTTP status code, body, and headers, then decodes the body. For async promises, the HTTP status code is set to null. Throws InvalidArgumentException if the response is not of the expected type.

### Method
Constructor

### Signature
```php
public function __construct(TelegramRequest $request, $response)
```

### Parameters
- **$request** (TelegramRequest) - Required - The original request that produced this response.
- **$response** (ResponseInterface|PromiseInterface) - Required - Raw HTTP response or a Guzzle promise for async calls.

### Behavior
- If `$response` is a `ResponseInterface`: stores HTTP status code, body string, headers, then calls `decodeBody()`.
- If `$response` is a `PromiseInterface`: sets `$httpStatusCode` to `null` (async, no body available yet).
- Otherwise: throws `InvalidArgumentException('Second constructor argument "response" must be instance of ResponseInterface or PromiseInterface')`.

### Notes
Normally constructed by `TelegramClient::getResponse()`; consumers rarely construct it directly.
```

--------------------------------

### setMyCommands() and getMyCommands() - Manage bot commands

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Methods-Misc.md

Sets a list of bot commands and then retrieves them. Requires command data as arrays; getMyCommands returns a collection of BotCommand objects.

```php
$telegram->setMyCommands([
    'commands' => [
        ['command' => 'start', 'description' => 'Start the bot'],
        ['command' => 'help',  'description' => 'Show help'],
    ],
]);
$commands = $telegram->getMyCommands();
```

--------------------------------

### setStickerSetThumb deprecated shim example

Source: https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/_autodocs/api-reference/Methods-Stickers.md

Shows usage of the deprecated setStickerSetThumb method, which renames 'thumb' to 'thumbnail' and defaults 'format' to 'static', delegating to setStickerSetThumbnail().

```php
$telegram->setStickerSetThumb(['name' => 'animals_by_example_bot', 'user_id' => 123, 'thumb' => $fileId]);
// equivalent to setStickerSetThumbnail(['name' => ..., 'user_id' => ..., 'thumbnail' => $fileId, 'format' => 'static'])
```
Tokens:
Raw