grayhoax/phptelebot

Telegram bot framework written in PHP with full Bot API 9.2 support.

Maintainers

Details

github.com/GrayHoax/phptelebot

Source

Installs: 266

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 1

Forks: 69

Type:framework

pkg:composer/grayhoax/phptelebot

v1.4.25 2025-11-23 20:02 UTC

Requires

Requires (Dev)

Suggests

GPL-3.0 8c7df05732021ac976352fcc3df6be0c51fbf4c9

  • Radya <radya.woop@gmx.com>
  • GrayHoax <grayhoax.woop@grayhoax.ru>

bottelegramtelegram-botbot-apiphp-telegram

This package is auto-updated.

Last update: 2025-12-23 20:13:51 UTC

README

Telegram bot framework written in PHP

Version 2.0 - Now with full support for Telegram Bot API 9.2 (2025)

Features

  • Simple, easy to use.
  • Support Long Polling and Webhook.
  • Full support for latest Telegram Bot API (v9.2).
  • Support for Forums, Business Accounts, Reactions, and more.
  • 100+ Telegram Bot API methods available.
  • Extensive event handling (40+ event types).

Requirements

  • cURL
  • PHP 5.4+
  • Telegram Bot API Token - Talk to @BotFather and generate one.

Installation

Using Composer

To install PHPTelebot with Composer, just add the following to your composer.json file:

{
    "require": {
        "grayhoax/phptelebot": "*"
    }
}

or by running the following command:

composer require grayhoax/phptelebot

Composer installs autoloader at ./vendor/autoloader.php. to include the library in your script, add:

require_once 'vendor/autoload.php';

Install from source

Download the PHP library from Github, then include PHPTelebot.php in your script:

require_once '/path/to/phptelebot/src/PHPTelebot.php';

Usage

Creating a simple bot

<?php

require_once './src/PHPTelebot.php';
$bot = new PHPTelebot('TOKEN', 'BOT_USERNAME'); // Bot username is optional, its required for handle command that contain username (/command@username) like on a group.

// Simple command
$bot->cmd('*', 'Hi, human! I am a bot.');

// Simple echo command
$bot->cmd('/echo|/say', function ($text) {
    if ($text == '') {
        $text = 'Command usage: /echo [text] or /say [text]';
    }
    return Bot::sendMessage($text);
});

// Simple whoami command
$bot->cmd('/whoami|!whoami', function () {
    // Get message properties
    $message = Bot::message();
    $name = $message['from']['first_name'];
    $userId = $message['from']['id'];
    $text = 'You are <b>'.$name.'</b> and your ID is <code>'.$userId.'</code>';
    $options = [
        'parse_mode' => 'html',
        'reply' => true
    ];

    return Bot::sendMessage($text, $options);
});

$bot->run();

Then run

php file.php

You can also see my other sample.

NOTE:

  • If function parameters is more than one, PHPTelebot will split text by space.
  • If you don't set chat_id on options bot will send message to current chat.
  • If you add option reply => true, bot will reply current message (Only work if you don't set custom chat_id and reply_to_mesage_id).

Commands

Use $bot->cmd(<command>, <function>) to handle command.

// simple answer
$bot->cmd('*', 'I am a bot');

// catch multiple commands
$bot->cmd('/start|/help', function () {
   // Do something here.
});

// call a function name
function googleSearch($search) {
   // Do something here.
}
$bot->cmd('/google', 'googleSearch');

Use * to catch any command.

File upload

This code will send a photo to users when type command /upload.

// Simple photo upload
$bot->cmd('/upload', function () {
    $file = '/path/to/photo.png'; // File path, file id, or url.
    return Bot::sendPhoto($file);
});

Events

Use $bot->on(<event>, <function>) to handle all possible PHPTelebot events.

To handle inline message, just add:

$bot->on('inline', function($text) {
    $results[] = [
        'type' => 'article',
        'id' => 'unique_id1',
        'title' => $text,
        'message_text' => 'Lorem ipsum dolor sit amet',
    ];
    $options = [
        'cache_time' => 3600,
    ];

    return Bot::answerInlineQuery($results, $options);
});

Also, you can catch multiple events:

$bot->on('sticker|photo|document', function() {
  // Do something here.
 });

Supported events:

Media Events

  • * - any type of message
  • text – text message
  • photo – photo
  • video – video file
  • animation – GIF or video without sound
  • video_note – circular video message
  • audio – audio file
  • voice – voice message
  • document – document file (any kind)
  • sticker – sticker
  • poll – native poll
  • dice – dice, darts, basketball, or other animated emoji

Location & Contact

  • contact – contact data
  • location – location data
  • venue – venue data

Service Messages

  • pinned_message – message was pinned
  • new_chat_members – new members were added
  • new_chat_member – new member was added
  • left_chat_member – member was removed
  • new_chat_title – new chat title
  • new_chat_photo – new chat photo
  • delete_chat_photo – chat photo was deleted
  • group_chat_created – group has been created
  • channel_chat_created – channel has been created
  • supergroup_chat_created – supergroup has been created
  • migrate_to_chat_id – group has been migrated to a supergroup
  • migrate_from_chat_id – supergroup has been migrated from a group
  • web_app_data – data from Web App
  • write_access_allowed – user allowed bot to write messages

Forum Events

  • forum_topic_created – forum topic created
  • forum_topic_edited – forum topic edited
  • forum_topic_closed – forum topic closed
  • forum_topic_reopened – forum topic reopened
  • general_forum_topic_hidden – general topic hidden
  • general_forum_topic_unhidden – general topic unhidden

Video Chat Events

  • video_chat_scheduled – video chat scheduled
  • video_chat_started – video chat started
  • video_chat_ended – video chat ended
  • video_chat_participants_invited – participants invited to video chat

Inline & Callback

  • inline - inline message
  • callback - callback message

Business Account Events (2024-2025)

  • business_connection – bot connected to business account
  • business_message – message from connected business account
  • edited_business_message – edited business message
  • deleted_business_messages – messages deleted from business account

Reactions & Boosts

  • message_reaction – reaction to message changed
  • message_reaction_count – reactions count changed
  • chat_boost – chat boost added
  • removed_chat_boost – boost removed

Member & Chat Updates

  • my_chat_member – bot's chat member status updated
  • chat_member – chat member status updated
  • chat_join_request – user requested to join chat

Payments

  • pre_checkout_query – pre-checkout query
  • shipping_query – shipping query

Other

  • edited – edited message
  • edited_message – edited message
  • game - game
  • channel - channel post
  • edited_channel - edited channel post
  • poll_update – poll state updated
  • poll_answer – user changed poll answer

Command with custom regex (advanced)

Create a command: /regex string number

$bot->regex('/^\/regex (.*) ([0-9])$/i', function($matches) {
    // Do something here.
});

Methods

PHPTelebot Methods

cmd(<command>, <answer>)

Handle a command.

on(<event>, <answer>)

Handles events.

regex(<regex>, <answer>)

Create custom regex for command.

Bot::type()

Return message event type.

Bot::message()

Get message properties.

Telegram Methods

PHPTelebot uses standard Telegram Bot API method names. All methods support the same parameters as documented in the official API.

Sending Messages & Media

Bot::getMe() ?

A simple method for testing your bot's auth token.

Bot::sendMessage(<text>, <options>) ?

Use this method to send text messages.

Bot::forwardMessage(<options>) ?

Use this method to forward messages of any kind.

Bot::copyMessage(<chat_id>, <options>) ?

Use this method to copy messages of any kind.

Bot::sendPhoto(<file path | file id | url>, <options>) ?

Use this method to send a photo.

Bot::sendVideo(<file path | file id | url>, <options>) ?

Use this method to send a video.

Bot::sendAnimation(<file path | file id | url>, <options>) ?

Use this method to send animation files (GIF or H.264/MPEG-4 AVC video without sound).

Bot::sendVideoNote(<file path | file id | url>, <options>) ?

Use this method to send video messages (rounded square mp4 videos).

Bot::sendAudio(<file path | file id | url>, <options>) ?

Use this method to send audio files.

Bot::sendVoice(<file path | file id | url>, <options>) ?

Use this method to send voice messages.

Bot::sendDocument(<file path | file id | url>, <options>) ?

Use this method to send documents.

Bot::sendSticker(<file path | file id | url>, <options>) ?

Use this method to send stickers.

Bot::sendMediaGroup(<media>, <options>) ?

Use this method to send a group of photos, videos, documents or audios as an album.

Bot::sendPoll(<question>, <options>) ?

Use this method to send a native poll. Supports up to 12 options.

Bot::sendDice(<emoji>, <options>) ?

Use this method to send an animated emoji (dice, darts, basketball, etc.).

Bot::sendLocation(<options>) ?

Use this method to send point on the map.

Bot::sendVenue(<options>) ?

Use this method to send information about a venue.

Bot::sendContact(<options>) ?

Use this method to send phone contacts.

Bot::sendChatAction(<action>, <options>) ?

Use this method when you need to tell the user that something is happening on the bot's side.

Bot::deleteMessage(<chat_id>, <options>) ?

Use this method to delete a message.

Bot::deleteMessages(<options>) ?

Use this method to delete multiple messages simultaneously.

Bot::getUserProfilePhotos(<user id>, <options>) ?

Use this method to get a list of profile pictures for a user.

Bot::getFile(<file id>) ?

Use this method to get basic info about a file and prepare it for downloading. For the moment, bots can download files of up to 20MB in size.

Bot::answerInlineQuery(<array of results>, <options>) ?

Use this method to send answers to an inline query.

Bot::answerCallbackQuery(<text>, <options>) ?

Use this method to send answers to callback queries sent from inline keyboards.

Bot::getChat(<chat_id>) ?

Use this method to get up to date information about the chat.

Bot::leaveChat(<chat_id>) ?

Use this method for your bot to leave a group, supergroup or channel.

Bot::setChatPhoto(<photo>, <options>) ?

Use this method to set a new profile photo for the chat.

Bot::deleteChatPhoto(<chat_id>) ?

Use this method to delete a chat photo.

Bot::setChatTitle(<chat_id>, <options>) ?

Use this method to change the title of a chat.

Bot::setChatDescription(<chat_id>, <options>) ?

Use this method to change the description of a group, supergroup or channel.

Bot::pinChatMessage(<message_id>, <options>) ?

Use this method to add a message to the list of pinned messages in a chat.

Bot::unpinChatMessage(<chat_id>, <options>) ?

Use this method to remove a message from the list of pinned messages in a chat.

Bot::unpinAllChatMessages(<options>) ?

Use this method to clear the list of pinned messages in a chat.

Bot::getChatAdministrators(<chat_id>) ?

Use this method to get a list of administrators in a chat.

Bot::getChatMemberCount(<chat_id>) ?

Use this method to get the number of members in a chat.

Bot::getChatMember(<options>) ?

Use this method to get information about a member of a chat.

Bot::banChatMember(<chat_id>, <options>) ?

Use this method to ban a user from a group, supergroup or channel.

Bot::unbanChatMember(<options>) ?

Use this method to unban a previously banned user in a supergroup or channel.

Bot::restrictChatMember(<chat_id>, <options>) ?

Use this method to restrict a user in a supergroup.

Bot::promoteChatMember(<chat_id>, <options>) ?

Use this method to promote or demote a user in a supergroup or a channel.

Bot::setChatAdministratorCustomTitle(<chat_id>, <options>) ?

Use this method to set a custom title for an administrator.

Bot::banChatSenderChat(<chat_id>, <options>) ?

Use this method to ban a channel chat in a supergroup or a channel.

Bot::unbanChatSenderChat(<chat_id>, <options>) ?

Use this method to unban a previously banned channel chat.

Bot::setChatPermissions(<options>) ?

Use this method to set default chat permissions for all members.

Bot::exportChatInviteLink(<chat_id>) ?

Use this method to generate a new primary invite link for a chat.

Bot::createChatInviteLink(<options>) ?

Use this method to create an additional invite link for a chat.

Bot::editChatInviteLink(<options>) ?

Use this method to edit a non-primary invite link.

Bot::revokeChatInviteLink(<options>) ?

Use this method to revoke an invite link.

Bot::approveChatJoinRequest(<chat_id>, <options>) ?

Use this method to approve a chat join request.

Bot::declineChatJoinRequest(<chat_id>, <options>) ?

Use this method to decline a chat join request.

Forum Topics

Bot::createForumTopic(<chat_id>, <options>) ?

Use this method to create a topic in a forum supergroup chat.

Bot::editForumTopic(<chat_id>, <options>) ?

Use this method to edit name and icon of a topic.

Bot::closeForumTopic(<chat_id>, <options>) ?

Use this method to close an open topic in a forum supergroup chat.

Bot::reopenForumTopic(<chat_id>, <options>) ?

Use this method to reopen a closed topic in a forum supergroup chat.

Bot::deleteForumTopic(<chat_id>, <options>) ?

Use this method to delete a forum topic.

Bot::unpinAllForumTopicMessages(<chat_id>, <options>) ?

Use this method to clear the list of pinned messages in a forum topic.

Bot::editGeneralForumTopic(<options>) ?

Use this method to edit the name of the 'General' topic.

Bot::closeGeneralForumTopic(<options>) ?

Use this method to close the 'General' topic in a forum supergroup chat.

Bot::reopenGeneralForumTopic(<options>) ?

Use this method to reopen the 'General' topic in a forum supergroup chat.

Bot::hideGeneralForumTopic(<options>) ?

Use this method to hide the 'General' topic in a forum supergroup chat.

Bot::unhideGeneralForumTopic(<options>) ?

Use this method to unhide the 'General' topic in a forum supergroup chat.

Bot::getForumTopicIconStickers() ?

Use this method to get custom emoji stickers for use as forum topic icons.

Reactions & Boosts

Bot::setMessageReaction(<chat_id>, <options>) ?

Use this method to change the chosen reactions on a message.

Bot::getUserChatBoosts(<chat_id>, <options>) ?

Use this method to get the list of boosts added to a chat by a user.

Games

Bot::sendGame(<game short name>, <options>) ?

Use this method to send a game.

Bot::setGameScore(<options>) ?

Use this method to set the score of the specified user in a game.

Bot::getGameHighScores(<user id>, <options>) ?

Use this method to get data for high score tables.

Stickers

Bot::uploadStickerFile(<user_id>, <options>) ?

Use this method to upload a file with a sticker.

Bot::createNewStickerSet(<options>) ?

Use this method to create a new sticker set.

Bot::addStickerToSet(<options>) ?

Use this method to add a new sticker to a set.

Bot::deleteStickerFromSet(<options>) ?

Use this method to delete a sticker from a set.

Bot::getStickerSet(<name>) ?

Use this method to get a sticker set.

Bot::deleteStickerSet(<name>) ?

Use this method to delete a sticker set.

Bot::getCustomEmojiStickers(<custom_emoji_ids>) ?

Use this method to get information about custom emoji stickers.

Payments & Stars

Bot::getMyStarBalance() ?

Use this method to get the bot's current balance of Telegram Stars.

Bot::getStarTransactions(<options>) ?

Use this method to get the list of bot's Star transactions.

Bot::refundStarPayment(<options>) ?

Use this method to refund a successful Star payment.

Bot::createInvoiceLink(<title>, <options>) ?

Use this method to create a link for an invoice.

Bot::answerShippingQuery(<shipping_query_id>, <options>) ?

Use this method to reply to shipping queries.

Bot::answerPreCheckoutQuery(<pre_checkout_query_id>, <options>) ?

Use this method to respond to pre-checkout queries.

Bot Configuration

Bot::getMyCommands(<options>) ?

Use this method to get the current list of the bot's commands.

Bot::setMyCommands(<options>) ?

Use this method to change the list of the bot's commands.

Bot::deleteMyCommands(<options>) ?

Use this method to delete the list of the bot's commands.

Business Account Management

Bot::getBusinessConnection(<business_connection_id>) ?

Use this method to get information about the connection with a business account.

Bot::setBusinessAccountName(<name>, <options>) ?

Use this method to change the name of a business account.

Bot::setBusinessAccountUsername(<username>, <options>) ?

Use this method to change the username of a business account.

For a complete list of all 100+ supported methods, see CHANGELOG.md or the official Telegram Bot API documentation.

Webhook installation

Open via browser https://api.telegram.org/bot<BOT TOKEN>/setWebhook?url=https://yourdomain.com/your_bot.php