Telebot2: A simple Telegram PHP Bot
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


This app is a very simple Telegram PHP API for newly announced Telegram Bots.

This PHP Script is totally rewrite of Telegram-bot-php.


  • By installing this script, you can have a working Telegram Bot within minutes!
  • This script only has one route to listen Post Request from Telegram API.
  • This script can handle multiple bots from same route. Different hooks will be different route parameters. I'm already hosting two different bots with the same application.
  • This app can send messages. It can also send photos, stickers, video and audio files, documents and locations.
  • Bot works on both private chats and groups.
  • The bot can either quote or send the response text directly.
  • You can enable or disable preview links in bots' responses.
  • Plugin Support! You can add your plugins and call them from any namespace :party:






  1. Set a new virtualhost and set the public folder as root. Don't forget to create rewrite rules, too. You can refer to Lumen's official documentation here
  2. Copy the app into your virtualhost.
  3. cd into the app's directory
  4. Run composer install and install dependencies.
  5. Copy .env.example to .env if not done already.
  6. Edit the .env.example file and fill all of the credentials.
  7. Create your Telegram bot if not already and commands and get the Access Token from Botfather.
  8. Run php artisan migrate to create database tables.
  9. Configure your Telegram Bot:
    • Run php artisan bot:create. It will ask some information
    • Fill the bot's name without the @ character. So if your bot's name is @HodorBot, type HodorBot.
    • On the second prompt, fill your Bot's Token.
    • After filling both the credentials, it will
  10. (Optional) Run php artisan db:seed to run demo seeder data, or check database/seeds/ExampleDataSeeder.php for example data.
  11. Send your first command to your newly Telegram bot and see it in action! 😄

Plugin Support

Within the rewrite of the script from scratch, now you will be able to use your own PHP classes from any namespace and run and implement them directly!

You just need to set a PHP class like this:


namespace Telebot\Plugins;

use Faker;

class ExamplePlugin
    private $responseData, //The response row from SQL 
        $request, //Bot's request data as array
        $config, //The whole config, along with plugin specific configuration
        $rawInput; //User's input
    // $config['global_config'] returns the Lumen configuration array
    // $config['global_env'] returns the environment variables

    public function __construct($responseData, $request, $config, $rawInput)
        $this->responseData = $responseData;
        $this->request = $request;
        $this->config = $config;
        $this->rawInput = $rawInput;

     * The response data for Telegram API
     * @return array
    public function setResponse()
        $faker = Faker\Factory::create();

        //For what to return, you can refer to Telebot.php or Telegram API
        return [
            'name' => 'text',
            'contents' => 'Hello human, ' . $faker->text,

     * The endpoint of Telegram, this defines how the message will be sent
     * @return string
    public function setEndpoint()
        return 'sendMessage';

And a row like this in responses table:

    'bot_id' => 1
    'command' => 'alinti', //Without the leading slash
    'pattern' => 'naber',
    'response_type' => 'external',
    'response_data' => 'ExamlePlugin',
    'plugin_namespace' => 'Telebot\Plugins', //These two lines will call \Telebot\Plugins\ExamplePlugin Class
    'as_quote' => 'y',
    'preview_links_if_any' => 'n',
    'created_at' => date('Y-m-d H:i:s'),
    'updated_at' => date('Y-m-d H:i:s'),

The above codes will produce a response such as this:


There is also another plugin called CurrentWeatherPlugin in the same folder. It connects to plugin with a provided dummy app key (you can set it in your .env file at PLUGIN_OPENWEATHERMAP_API_KEY) and get a response such as this:


As you can see, the namespace is defined at it's row. You can copy and paste your plugin into telebot/plugins directory (it won't be tracked), or call it as a requirement from composer and just set the class name and namespace.


  • If there are more than one matches, a random one is chosen. So there may be more than one responses for matching patterns.
  • The script checks the matching words from the bot with preg_match(). A code like preg_match('/pattern/i', $userInput) is run to match the responses with given user input.
  • Location has latitude and longtitude parameters, but since there is only one response_data column, you have to use | character as delimiter. Example location response_data for Istanbul, Turkey: 41.015137|28.979530.
  • Please see database/seeds/ExampleDataSeeder.php for all of the examples.
  • Personally, I'd suggest every response to have commands, because sometimes the @botMention, especially on the case when commands are set for it, don't work.


  • Inline Bots support
  • Caching
  • More plugins
  • ?


  • Fork the project,
  • Do your magic,
  • Send a pull request


0.3.1 - release 2016-06-17

  • Parameters are non mandatory for responses and plugins: Some plugins may directly need parameters for specific commands, such as /command parameter where the parameter may directly be a specific response's parameter. But make sure you don't have a command pattern matching parameter for this case, else they are also being returned. This way, you can use /command parameter directly from now on.
  • Another example plugin, "Google TTS Plugin". This plugin returns the user's text as response speech.
  • Better response handling. If results were expected and no result was returned, the script would throw an exception.

0.3.0 - release 2016-06-17

  • Plugins can can now import user input, the config and environment variables.
  • Example Weather bot added ( telebot/Plugins/CurrentWeatherPlugin.php ), which is powered by OpenWeatherMap (you must set your free api key).

0.2.2 - release 2016-06-17

  • Proper response handling.

0.2.1 - release 2016-06-16

  • Fix to not to send the default response to invalid commands.
  • Non-valid commands are not returning response from now on.
  • The bot can now also response to messages such as /command@nameOfTheBot message.

0.2.0 - release 2016-06-15

  • You can now set the default response for the bot if there's no matching results.

0.1.0 - release 2016-06-15

  • Initial Release.