PHPackages                             bahramali/telegram-bot-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PSR & Standards](/categories/psr-standards)
4. /
5. bahramali/telegram-bot-php

ActiveLibrary[PSR & Standards](/categories/psr-standards)

bahramali/telegram-bot-php
==========================

Telegram-Bot-PHP is a PHP library for interacting with the official Telegram Bot API

v1.1.1(4y ago)91081MITPHPPHP >=7.4

Since Jul 27Pushed 4y ago1 watchersCompare

[ Source](https://github.com/ErfanBahramali/Telegram-Bot-PHP)[ Packagist](https://packagist.org/packages/bahramali/telegram-bot-php)[ Docs](https://github.com/ErfanBahramali/Telegram-Bot-PHP)[ RSS](/packages/bahramali-telegram-bot-php/feed)WikiDiscussions main Synced today

READMEChangelog (3)DependenciesVersions (4)Used By (0)

Telegram Bot PHP
================

[](#telegram-bot-php)

Telegram Bot PHP is a PHP Library for interaction with [Telegram Bot API](https://core.telegram.org/bots/api) 5.4 (November 5, 2021).

Table
-----

[](#table)

- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Security](#security)
- [Config](#config)
    - [Configs](#configs)
    - [Logging](#logging)
        - [onLog](#onlog)
        - [onLogUpdate](#onlogupdate)
        - [onLogRequestAndResponse](#onlogrequestandresponse)
        - [onLogError](#onlogerror)
    - [Main Config](#main-config)
    - [Use Config](#use-config)
    - [Set Config](#set-config)
- [Update](#update)
    - [Webhook](#webhook)
    - [Get Updates](#get-updates)
- [Methods](#methods)
    - [Keyboards](#keyboards)
- [Response](#response)
    - [Get Response](#get-response)
    - [Result](#result)
    - [Example](#example)
    - [Error](#error)
    - [Request](#request)
- [Download File](#download-file)
- [Helper](#helper)
- [Format](#format)
- [Exceptions](#exceptions)
- [Update Type](#update-type)
- [Chat Action](#chat-action)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)
- [About Us](#about-us)
- [License](#license)

Requirements
------------

[](#requirements)

**Please read the [Telegram API document](https://core.telegram.org/bots/api) at least once**

- Read [Telegram API document](https://core.telegram.org/bots/api)
- php >=7.4
- ext-curl: \*
- ext-json: \*
- ext-mbstring: \*
- ext-openssl: \*

Installation
------------

[](#installation)

Use composer to require it,

```
composer require bahramali/telegram-bot-php

```

**or**

```
php composer.phar require bahramali/telegram-bot-php

```

**or**

Create `composer.json` file and add

```
{
    "name": "/",
    "require": {
        "bahramali/telegram-bot-php": "*"
    }
}

```

and run

```
composer update

```

**Note:** If you don't have [Composer](https://getcomposer.org/) you can download it [HERE](https://getcomposer.org/download/).

Usage
-----

[](#usage)

To use this library, you need to require the Composer Autoloader And create a new object from the bot class

**Please read the [Telegram API document](https://core.telegram.org/bots/api) at least once**

```
use TelegramBotPHP\Bot;

require_once __DIR__ . '/vendor/autoload.php';

/**
 * @link https://core.telegram.org/bots/api#authorizing-your-bot
 */
$bot = new Bot('__BOT_API_TOKEN__');
```

Security
--------

[](#security)

**You can add a specific parameter to your webhook url so that only you know about that link.**

#### Example:

[](#example)

```
https://example.com/bot?example=1a79a4d60de6718e8e5b326e338ae533

```

**Then check in your code the parameter that must be present**

```
if ($_GET['example'] == '1a79a4d60de6718e8e5b326e338ae533') {
    // code
} else {
    // 404 not found
}
```

**Be sure to check that the IP is the sender of the Telegram IP.**

**You can use the 'isTelegramIp' function of 'bot' class to check Telegram IP**

#### Example:

[](#example-1)

```
$ip = $_SERVER['REMOTE_ADDR'];

if (Bot::isTelegramIp($ip)) {
    // code
} else {
    // 404 not found
}
```

Config
------

[](#config)

### Configs

[](#configs)

**You can adjust the configuration and change it in each section**

if you are using a local bot api server, Set up your server url

```
/**
 * bot api server url
 * @link https://core.telegram.org/bots/api#using-a-local-bot-api-server
 */
public string $botApiServerUrl = 'https://api.telegram.org/bot'; // https://example.com/bot{__BOT_API_TOKEN__}/MethodName?parameters=values
```

if you are using a local bot api server, Set up your server file url, for download file

```
/**
 * bot api server file url
 * @link https://core.telegram.org/bots/api#file
 */
public string $botApiServerFileUrl = 'https://api.telegram.org/file/bot'; // https://example.com/example/file/bot{__BOT_API_TOKEN__}/{__FILE_PATH__}
```

Convert updates and response to objects for easier access

Also you can set the variable to false and receive updates and response as an array

```
/**
 * auto convert update and response to class For easier access
 */
public bool $convertToObject = true;
```

If you don't want to use Webhook automatically, set this variable to false

```
/**
 * Use webhook by default
 * if use getUpdates Set this variable to false
 */
public bool $autoUseWebhook = true;
```

If you don't want some methods to have some of their parameters automatically, set this variable to false

**Its accuracy is not always guaranteed**

```
/**
 * In certain methods, some parameters are filled in automatically
 *
 * For example, in `sendMessage` method,

 * You can, not set "chat_id",

 * And the "chat_id" of the sender is considered automatic.
 */
public bool $autofillParameters = true;
```

If you want the program to continue after the error, set this variable to false

**This is only for when the response code of the submitted request is not equal to 200**

```
/**
 * Stop the program when it encounters an error
 */
public bool $throwOnError = true;
```

### Logging

[](#logging)

This library can log all their update , requests , responses and errors

Just set the function for the desired log

**You can change any of the functions anywhere in the app**

Get the information and you can use any method you want to record it

#### onLog

[](#onlog)

For updates , requests , responses and errors

At the end, the program is called and sends update and a list of all requests and responses and errors as input

##### Example

[](#example-2)

```
$config->onLog = function (array $log) {

    $log = json_encode($log);
    file_put_contents(__DIR__ . '/Bot.log', "{$log}\n", FILE_APPEND);
};
```

#### onLogUpdate

[](#onlogupdate)

For update only

When the update is received, the function is called

##### Example

[](#example-3)

```
$config->onLogUpdate = function (array $update) {

    $logUpdate = json_encode($update);
    file_put_contents(__DIR__ . '/Bot_update.log', "{$logUpdate}\n", FILE_APPEND);
};
```

#### onLogRequestAndResponse

[](#onlogrequestandresponse)

For requests and responses only

When a request is sent and the response code is 200

##### Example

[](#example-4)

```
$config->onLogRequestAndResponse = function (array $request, array $response) {

    $logRequestAndResponse = [$request, $response];
    $logRequestAndResponse = json_encode($logRequestAndResponse);
    file_put_contents(__DIR__ . '/Bot_request_response.log', "{$logRequestAndResponse}\n", FILE_APPEND);
};
```

#### onLogError

[](#onlogerror)

For errors only

When a request is sent and the response code is not 200

##### Example

[](#example-5)

```
$config->onLogError = function (array $error) {

    $logError = json_encode($error);
    file_put_contents(__DIR__ . '/Bot_error.log', "{$logError}\n", FILE_APPEND);
};
```

### Main Config

[](#main-config)

The main configuration is constant everywhere in the program And when a new configuration is created, the default value is the value set for the main configuration.

You can adjust the main configuration and change it in each section

**Note: You can see the default values [above](#configs)**

#### Use

[](#use)

It should only be used statically

```
MainConfig::$onLog = function (array $log) {

    $log = json_encode($log);
    file_put_contents(__DIR__ . '/Bot.log', "{$log}\n", FILE_APPEND);
};

// MainConfig::.... = ... ;
```

### Use Config

[](#use-config)

Just create an object of config class and change the values

**Note: The default configuration values are the [Main configuration](#main-config) values**

```
$config = new Config();

$config->onLog = function (array $log) {

    $log = json_encode($log);
    file_put_contents(__DIR__ . '/Bot.log', "{$log}\n", FILE_APPEND);
};

$config->onLogUpdate = function ($update) {

    $logUpdate = json_encode($update);
    file_put_contents(__DIR__ . '/Bot_update.log', "{$logUpdate}\n", FILE_APPEND);
};

// $config-> ... = ... ;
```

### Set

[](#set)

To use the created configuration, it can be set to the second parameter of the bot class

```
$bot = new Bot('__BOT_API_TOKEN__' , $config);
```

It can also be changed later if needed

```
$config->throwOnError = true;
// or
$bot->config->throwOnError = true;

$config->onLog = function (array $log) {

    $log = json_encode($log);
    file_put_contents(__DIR__ . '/Bot.log', "{$log}\n", FILE_APPEND);
};

// $bot->config->... = ...;
```

Update
------

[](#update)

There are two ways to receive the update

**There is no difference between camelCase and under\_score to get the parameters**

### Webhook

[](#webhook)

If you are using a webhook you can get updates using the 'getUpdate' and 'getInput' functions

```
// Do not confuse this function with the 'getUpdates' method of Telegram, it is 'getupdate'
$update = $bot->getUpdate(); // TelegramBotPHP\Types\Update Object ([updateId] => 585985242 [message] => TelegramBotPHP\Types\Message Object ( ... ))

$update = $bot->getInput(); // Array ([update_id] => 585985243 [message] => Array ( ... ))
```

#### Example

[](#example-6)

```
$update = $bot->getUpdate(); // TelegramBotPHP\Types\Update Object ([updateId] => 585985242 [message] => TelegramBotPHP\Types\Message Object ( ... ))

$messageId = $update->message->message_id; // 28236
// or
$messageId = $update->message->messageId; // 28236

$text = $update->message->text; // Example Text

// or
$update = $bot->getInput(); // Array ([update_id] => 585985243 [message] => Array ( ... ))

$messageId = $update['message']['message_id']; // 28236

$text = $update['message']['text']; // Example Text
```

### Get Updates

[](#get-updates)

Returns an array of update object

```
$updates = $bot->getUpdates()->getResult();// Array ([0] => TelegramBotPHP\Types\Update Object ( ... ) [1] => TelegramBotPHP\Types\Update Object ( ... ) [2] => TelegramBotPHP\Types\Update Object ( ... ))
```

#### Example:

[](#example-7)

```
$updates = $bot->getUpdates()->getResult();// Array ([0] => TelegramBotPHP\Types\Update Object ( ... ) [1] => TelegramBotPHP\Types\Update Object ( ... ) [2] => TelegramBotPHP\Types\Update Object ( ... ))
foreach ($updates as $key => $update) {

    $chatId = $update->chat->id; // 184171927
    // or you can create helper
}
```

Methods
-------

[](#methods)

To use the methods, all you have to do is type in the name of the method and pass an array of parameters listed in the [Telegram api document](https://core.telegram.org/bots/api#available-methods).

```
// now you can use all of telegram methods

$bot->methodName([
    // parameters
    'example' => 'test',
]);
```

#### Example:

[](#example-8)

```
// https://core.telegram.org/bots/api#available-methods

// chat_id is Unique identifier for the target chat or username of the target channel (in the format @channelusername)

// send message
$bot->sendMessage([
    'chat_id' => 184171927,
    'text' => 'Example Text',
]);

// send photo
$bot->sendPhoto([
    'chat_id' => 184171927,
    'photo' => new CURLFile('example.png'),
    'caption' => 'Example caption',
]);

// send document
$bot->sendDocument([
    'chat_id' => 184171927,
    'document' => new CURLFile('example.zip'),
    'caption' => 'Example caption',
]);

// ...
// $bot->...([
//   ...
// ]);
```

You can also use static

#### Example:

[](#example-9)

```
// send message
Bot::sendMessage([
    'chat_id' => 184171927,
    'text' => 'Example Text',
]);

// send photo
Bot::sendPhoto([
    'chat_id' => 184171927,
    'photo' => new CURLFile('example.png'),
    'caption' => 'Example caption',
]);

// send document
Bot::sendDocument([
    'chat_id' => 184171927,
    'document' => new CURLFile('example.zip'),
    'caption' => 'Example caption',
]);
```

Also to use different **BOT\_API\_TOKEN**

You can in the second parameter of each method, Enter a new **BOT\_API\_TOKEN**

#### Example:

[](#example-10)

```
// send message
Bot::sendMessage([
    'chat_id' => 184171927,
    'text' => 'Example Text',
], '__BOT_API_TOKEN__');
```

### Keyboards

[](#keyboards)

#### InlineKeyboardMarkup

[](#inlinekeyboardmarkup)

```
// send message
$bot->sendMessage([
    'chat_id' => 184171927,
    'text' => 'Example Text',
    'reply_markup' => [
        'inline_keyboard' =>
        [
            [['text' => 'one', 'callback_data' => 'one'], ['text' => 'two', 'callback_data' => 'two']],

            [['text' => 'three', 'callback_data' => 'three'], ['text' => 'four', 'callback_data' => 'four']],

            [['text' => 'url', 'url' => 'https://github.com/ErfanBahramali/Telegram-Bot-PHP']],
        ]
    ]
]);
```

#### ReplyKeyboardMarkup

[](#replykeyboardmarkup)

```
// send message
$bot->sendMessage([
    'chat_id' => 184171927,
    'text' => 'Example Text',
    'reply_markup' => [
        'keyboard' =>
        [
            [['text' => 'one'], ['text' => 'two']],

            [['text' => 'three'], ['text' => 'four']],

            [['text' => 'request contact', 'request_contact' => true]],

            [['text' => 'request location', 'request_location' => true]],
        ],
        'resize_keyboard' => true,
    ]
]);
```

#### ReplyKeyboardRemove

[](#replykeyboardremove)

```
// send message
$bot->sendMessage([
    'chat_id' => 184171927,
    'text' => 'Example Text',
    'reply_markup' => [
        'remove_keyboard' => true
    ]
]);
```

#### ForceReply

[](#forcereply)

```
// send message
$bot->sendMessage([
    'chat_id' => 184171927,
    'text' => 'Example Text',
    'reply_markup' => [
        'force_reply' => true,
        'input_field_placeholder' => 'test',
    ]
]);
```

Response
--------

[](#response)

**There is no difference between camelCase and under\_score to get the parameters**

### Get Response

[](#get-response)

```
$response = $bot->methodName([
    // parameters
    'example' => 'test',
]); // (TelegramBotPHP\Response\Response Object( .... ))
```

### Result

[](#result)

```
// {
//   "ok": true,
//   "result": {
//     "message_id": 28236,
//     "from": {
//       "id": 93372553,
//       "is_bot": true,
//       "first_name": "BotFather",
//       "username": "BotFather"
//     },
//     "chat": {
//       "id": 184171927,
//       "first_name": "Erfan",
//       "type": "private"
//     },
//     "date": 1627277790,
//     "text": "Example Text"
//   }
// }

$response->isOk(); // check response ok is true (true)

$response->getResult(); // get response Result. The result is not always an object and may be an array and a bool (TelegramBotPHP\Types\Message Object([messageId] => 28236 [from] => TelegramBotPHP\Types\User Object( ... ) [date] => 1627277790[chat] => TelegramBotPHP\Types\Chat Object( ... )[text] => Example Text))

$response->getResponseData(); // get all of response as an array (Array ([ok] => 1 [result] => Array ( [message_id] => 28236 [from] => Array  ( ... ) [chat] => Array ( ... ) [date] => 1627277790 [text] => Example Text )))
```

### Example:

[](#example-11)

```
$result = $response->getResult();// TelegramBotPHP\Types\Message Object( ... )

$messageId = $result->message_id; // 28236
$chatId = $result->chat->id; // 184171927
$text = $result->text; // Example Text

// or in array
$result = $response->getResponseData(); // Array ( ... )
$result = $result['result']; // Array ( ... )

$messageId = $result['message_id']; // 28236
$chatId = $result['chat']['id']; // 184171927
$text = $result['text']; // Example Text
```

### Error:

[](#error)

```
// {
//   "ok": false,
//   "error_code": 400,
//   "description": "Bad Request: chat not found"
// }

$response->getErrorCode(); // check response error_code (400)
$response->getDescription(); // check response description ("Bad Request: chat not found")
```

### Request:

[](#request)

```
$response->getRequestMethod(); // get request method name (sendMessage)
$response->getRequestParameters(); // get request parameters as an array (['chat_id' => '184171927', 'text' => 'Example Text'])
```

Download File
=============

[](#download-file)

```
// downloadFile($filePath, $localFilePath)

// $fileSource = self::$config->botApiServerFileUrl . self::$token . '/' . $filePath;

$bot->downloadFile('documents/example.txt', __DIR__ . '/documents/example.txt');

// $fileSource = self::$config->botApiServerFileUrl . self::$token . '/' . 'documents/example.txt';

// or

Bot::downloadFile('documents/example.txt', __DIR__ . '/documents/example.txt');
```

### download file by file\_id

[](#download-file-by-file_id)

```
// downloadFileByFileId($fileId, $localFilePath)

$bot->downloadFileByFileId('BQACAgQAAxkBAAJ0T2EJUDHTeXGcSBUrqFMgzZCQ0OJGAAIhCQACg2tJUEqm6016cXE9IAQ', __DIR__ . '/documents/example.txt');

// or

Bot::downloadFileByFileId('BQACAgQAAxkBAAJ0T2EJUDHTeXGcSBUrqFMgzZCQ0OJGAAIhCQACg2tJUEqm6016cXE9IAQ', __DIR__ . '/documents/example.txt');
```

Helper
------

[](#helper)

Helpers are auxiliary functions for receiving certain values or checking some items or doing certain tasks

**Note: You can see the full list of functions in the [`Helpers Folder`](https://github.com/ErfanBahramali/Telegram-Bot-PHP/tree/main/src/Helpers)**

**There is no difference between camelCase and under\_score to get the parameters**

#### Example:

[](#example-12)

```
$chatId = $bot->getHelper()->getChatId();
// or
$chatId = Helper::getChatId();
// or
$chatId = $bot->getUpdate()->message->chat->id;
```

You can also create a new helper with the input update array

```
$helper = new Helper({__Input_Update_Array__});

// Example:
$helper = new Helper($bot->getInput());
```

Of course, the bot builds the helper itself and there is no need to build a helper with its value, You can get the bot helper with 'getHelper'

#### Example:

[](#example-13)

```
$helper = $bot->getHelper();
```

Format
------

[](#format)

The Format class is a class to help create different text formats

#### Mention

[](#mention)

You can easily mention users

```
$text = Format::mention('184171927','Erfan'); // [Erfan](tg://user?id=184171927)
```

#### Styles

[](#styles)

```
// escape markdownV2 style
$text = Format::markdownV2('');

// escape HTML style
$text = Format::html('');

// escape markdown style
$text = Format::markdown('');
```

#### Example:

[](#example-14)

```
// escape markdownV2 style
$text = Format::markdownV2('*bold \*text*'); // \*bold \\\*text\*

// escape HTML style
$text = Format::html('bold, bold'); // <b>bold</b>, <strong>bold</strong>

// escape markdown style
$text = Format::markdown('*bold text*'); // \*bold text\*
```

#### Example:

[](#example-15)

```
$text = Format::markdownV2('*bold \*text*');

Bot::sendMessage([
    'chat_id' => '184171927',
    'text' => "*{$text}*",
    'parse_mode' => ParseMode::MARKDOWNV2,
]);
```

Exceptions
----------

[](#exceptions)

You can manage errors with [try catch](https://www.php.net/manual/en/language.exceptions.php)

**BotException:** Main exception class used for exception handling

**BotLogException:** exception class used for log

**BotNotSupportException:** exception class Thrown when Feature not support

Update Type
-----------

[](#update-type)

If you want to check the type of updates

You can use helpers

**You can see the full list of 'updateTypeIs...' functions in the [`helper type class`](https://github.com/ErfanBahramali/Telegram-Bot-PHP/blob/main/src/Helpers/Helper.php)**

#### Example:

[](#example-16)

```
if (Helper::updateTypeIsMessage()) {
    # code...
} elseif (Helper::updateTypeIsCallbackQuery()) {
    # code...
} elseif (Helper::updateTypeIsMyChatMember()) {
    # code...
}

// or ...
// Helper::updateTypeIs...()
```

**Or**

You can use the 'getUpdateType' helper to get the type of update and then check it using different types of updates

**You can see the full list of update types in the [`update type class`](https://github.com/ErfanBahramali/Telegram-Bot-PHP/blob/main/src/Constants/UpdateType.php)**

#### Example:

[](#example-17)

```
$updateType = Helper::getUpdateType();

if ($updateType === UpdateType::MESSAGE) {

} elseif ($updateType === UpdateType::EDITED_MESSAGE) {

} elseif ($updateType === UpdateType::CALLBACK_QUERY) {

}
```

Chat Action
-----------

[](#chat-action)

You can use existing chat actions to send chat action

**You can see the full list of chat actions in the chat [`action class`](https://github.com/ErfanBahramali/Telegram-Bot-PHP/blob/main/src/Constants/ChatAction.php)**

#### Example:

[](#example-18)

```
Bot::sendChatAction([
    'chat_id' => 184171927,
    'action' => ChatAction::TYPING,
]);

Bot::sendChatAction([
    'chat_id' => 184171927,
    'action' => ChatAction::RECORD_VOICE,
]);

Bot::sendChatAction([
    'chat_id' => 184171927,
    'action' => ChatAction::FIND_LOCATION,
]);
```

Examples
--------

[](#examples)

- [`parrot`](https://github.com/ErfanBahramali/Telegram-Bot-PHP/blob/main/examples/Parrot/index.php)

Troubleshooting
---------------

[](#troubleshooting)

please report any bugs you find on the [issues](https://github.com/ErfanBahramali/Telegram-Bot-PHP/issues) page.

About Us
--------

[](#about-us)

This library can be used for easy interaction with [Telegram Bot API](https://core.telegram.org/bots/api)

License
-------

[](#license)

Telegram-Bot-PHP is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity16

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~22 days

Total

3

Last Release

1705d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/14eed73dace8db0125c528713a1a37ce5c5c73ab5a5670bead544a594c630c1c?d=identicon)[Erfan\_Bahramali](/maintainers/Erfan_Bahramali)

---

Top Contributors

[![ErfanBahramali](https://avatars.githubusercontent.com/u/77061285?v=4)](https://github.com/ErfanBahramali "ErfanBahramali (34 commits)")

---

Tags

bothacktoberfesthacktoberfest2023phppsr-4telegramtelegram-bottelegram-bot-apitelegram-bot-phpphpbotPSR-4telegramTelegram-Bot-PHP

### Embed Badge

![Health badge](/badges/bahramali-telegram-bot-php/health.svg)

```
[![Health](https://phpackages.com/badges/bahramali-telegram-bot-php/health.svg)](https://phpackages.com/packages/bahramali-telegram-bot-php)
```

###  Alternatives

[icamys/php-sitemap-generator

Simple PHP sitemap generator.

175342.8k6](/packages/icamys-php-sitemap-generator)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)