atanych/telegram-bot

PHP telegram bot (it is fork from longman/telegram-bot)

PHP Telegram Bot

, _(*1)

, _(*2)

A Telegram Bot based on the official Telegram Bot API, _(*3)

Introduction

This is a pure php Telegram Bot, fully extensible via plugins. Telegram recently announced official support for a Bot API allowing integrators of all sorts to bring automated interactions to the mobile platform. This Bot aims to provide a platform where one could simply write a plugin and have interactions in a matter of minutes. The Bot can: - retrive update with webhook and getUpdate methods. - supports all types and methods according to Telegram API (2015 October 8). - handle commands in chat with other bots., _(*4)

It is ready for the channels support., _(*5)

Instructions

Create your first bot

1. Message @botfather https://telegram.me/botfather with the following text: /newbot If you don't know how to message by username, click the search field on your Telegram app and type @botfather, you should be able to initiate a conversation. Be careful not to send it to the wrong contact, because some users has similar usernames to botfather., _(*6)

   , _(*7)

2. @botfather replies with Alright, a new bot. How are we going to call it? Please choose a name for your bot., _(*8)

3. Type whatever name you want for your bot., _(*9)

4. @botfather replies with Good. Now let's choose a username for your bot. It must end inbot. Like this, for example: TetrisBot or tetris_bot., _(*10)

5. Type whatever username you want for your bot, minimum 5 characters, and must end with bot. For example: telesample_bot, _(*11)

6. @botfather replies with:, _(*12)

   Done! Congratulations on your new bot. You will find it at telegram.me/telesample_bot. You can now add a description, about section and profile picture for your bot, see /help for a list of commands., _(*13)

   Use this token to access the HTTP API: 123456789:AAG90e14-0f8-40183D-18491dDE, _(*14)

   For a description of the Bot API, see this page: https://core.telegram.org/bots/api, _(*15)

7. Note down the 'token' mentioned above., _(*16)

8. Type /setprivacy to @botfather., _(*17)

   , _(*18)

9. @botfather replies with Choose a bot to change group messages settings., _(*19)

10. Type @telesample_bot (change to the username you set at step 5 above, but start it with @), _(*20)

11. @botfather replies with, _(*21)

    'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username. 'Disable' - your bot will receive all messages that people send to groups. Current status is: ENABLED, _(*22)

12. Type Disable to let your bot receive all messages sent to a group. This step is up to you actually., _(*23)

13. @botfather replies with Success! The new status is: DISABLED. /help, _(*24)

Require this package with Composer

Install this package through Composer. Edit your project's composer.json file to require longman/telegram-bot., _(*25)

Create composer.json file:, _(*26)

{
    "name": "yourproject/yourproject",
    "type": "project",
    "require": {
        "php": ">=5.4.0",
        "longman/telegram-bot": "*"
    }
}

And run composer update, _(*27)

Or run a command in your command line:, _(*28)

composer require longman/telegram-bot

Choose how to retrieve Telegram updates

The bot can handle updates with webhook or getUpdate method:, _(*29)

Webhook installation

You need server with https and composer support. You must set a WebHook. Create set.php (just edit example-set.php) and put into it:, _(*30)

<?php
//Composer Loader
$loader = require __DIR__.'/vendor/autoload.php';

$API_KEY = 'your_bot_api_key';
$BOT_NAME = 'namebot';
$link = 'https://yourdomain/yourpath_to_hook.php';
try {
    // create Telegram API object
    $telegram = new Longman\TelegramBot\Telegram($API_KEY, $BOT_NAME);
    // set webhook
    $result = $telegram->setWebHook($link);
    if ($result->isOk()) {
        echo $result->getDescription();
    }
} catch (Longman\TelegramBot\Exception\TelegramException $e) {
    echo $e;
}

And open your set.php via browser., _(*31)

After, create hook.php (or just edit example-hook.php) and put:, _(*32)

<?php
$loader = require __DIR__.'/vendor/autoload.php';

$API_KEY = 'your_bot_api_key';
$BOT_NAME = 'namebot';

try {
    // create Telegram API object
    $telegram = new Longman\TelegramBot\Telegram($API_KEY, $BOT_NAME);

    // handle telegram webhook request
    $telegram->handle();
} catch (Longman\TelegramBot\Exception\TelegramException $e) {
    // log telegram errors
    // echo $e;
}

Self Signed Certificate

To upload the certificate, add the certificate path as param in set.php:, _(*33)

$result = $telegram->setWebHook($url, $certificate_path);

getUpdate installation

You need the database Mysql active., _(*34)

Create getUpdateCLI.php (just edit example-getUpdateCLI.php) and put into it:, _(*35)

#!/usr/bin/env php
<?php
$loader = require __DIR__.'/vendor/autoload.php';

$API_KEY = 'your_bot_api_key';
$BOT_NAME = 'namebot';
$credentials = array('host'=>'localhost', 'user'=>'dbuser', 'password'=>'dbpass', 'database'=>'dbname');

try {
    // create Telegram API object
    $telegram = new Longman\TelegramBot\Telegram($API_KEY, $BOT_NAME);
    $telegram->enableMySQL($credentials);
    // handle telegram getUpdate request
    $telegram->handleGetUpdates();
} catch (Longman\TelegramBot\Exception\TelegramException $e) {
    // log telegram errors
     echo $e;
}                

give to the file the permission for execution:, _(*36)

chmod 775 getUpdateCLI.php

then run, _(*37)

./getUpdateCLI.php

Types

All types implemented according to Telegram API (2015 October 8)., _(*38)

Methods New!

All methods implemented according to Telegram API (2015 October 8)., _(*39)

Send Photo

To send a local photo provide the file path as second param:, _(*40)

$data['chat_id'] = $chat_id;
$result = Request::sendPhoto($data,$this->telegram->getUploadPath().'/'.'image.jpg');

If you know the file_id of a previously uploaded file, just provide it in the fist param:, _(*41)

$data['chat_id'] = $chat_id;
$data['photo'] = $file_id;
$result = Request::sendPhoto($data);

sendAudio, sendDocument, sendSticker, sendVideo and sendVoice works in the same way. See ImageCommand.php for a full example., _(*42)

Send Chat Action

Request::sendChatAction(['chat_id' => $chat_id, 'action' => 'typing']);

getUserProfilePhoto

Retrieve the user photo, see the WhoamiCommand.php for a full example., _(*43)

GetFile and dowloadFile

Get the file path and download it, see the WhoamiCommand.php for a full example., _(*44)

Send message to all active chats

To do this you have to enable the Mysql connection. Here's an example of use:, _(*45)

$results = $telegram->sendToActiveChats(
        'sendMessage', //callback function to execute (see Request.php methods)
        array('text'=>'Hey! Checkout the new feature!!'), //Param to evaluate the request
        true, //Send to chats (group chat)
        true, //Send to users (single chat)
        null, //'yyyy-mm-dd hh:mm:ss' date range from
        null  //'yyyy-mm-dd hh:mm:ss' date range to
    );

Utilis

MySQL storage (Recomended)

If you want insert in database messages/users/chats for further usage in commands, create database and import structure.sql and enable Mysql support after object creation and BEFORE handle method:, _(*46)

$credentials = array('host'=>'localhost', 'user'=>'dbuser',
'password'=>'dbpass', 'database'=>'dbname');

$telegram->enableMySQL($credentials);

You can set a custom prefix to all the tables while you are enabling Mysql:, _(*47)

$telegram->enableMySQL($credentials, $BOT_NAME.'_');

Commands

The bot is able to recognise commands in chat with multiple bot (/command@mybot ). It can execute command triggering a chat event. Here's the list:, _(*48)

• Group chat created (GroupchatcreatedCommand.php)
• New chat participant (NewchatparticipantCommand.php)
• Delete chat photo (DeletechatphotoCommand.php)
• New chat title (NewchattitleCommand.php)
• Left chat participant (LeftchatparticipantCommand.php)

GenericCommand.php let you handle commands that don't exist or to use commands as a variable: Favourite colour? /black, /red Favourite number? /1, /134, _(*49)

GenericmessageCommand.php let you handle any type of message., _(*50)

Maybe you would like to develop your own commands. A good practice is to store them outside vendor/. This can be done adding the method:, _(*51)

$COMMANDS_FOLDER = __DIR__.'/Commands/';
$telegram->addCommandsPath($COMMANDS_FOLDER);

Inside CommandsExamples/ there are some sample that show how to use types., _(*52)

Admin Commands

Enabling this feature, the admin bot can perform some super user command like: - Send message to all chats - List all the chats started with the bot (new!), _(*53)

You can specify one or more admin with this option:, _(*54)

$telegram->enableAdmins(array('TelegramUserID','Othersid'));

Telegram user id can be retrieved with the command /whoami. Admin commands are stored in src/Admin/ folder. To know all the commands avaiable type /help., _(*55)

Commands Configuration

With this method you can set some command specified parameters, for example, google geocode/timezone api key for date command:, _(*56)

$telegram->setCommandConfig('date',
array('google_api_key'=>'your_google_api_key_here'));

Upload and Download directory

You can overwrite the default Upload and Download directory with:, _(*57)

$telegram->setDownloadPath("yourpath/Download");
$telegram->setUploadPath("yourpath../Upload");    

Logging

Thrown Exception are stored in TelegramException.log file (in the base directory)., _(*58)

Incoming update (json string from webhook and getUpdates) can be logged on a text file, set those options with the methods:, _(*59)

$telegram->setLogRequests(true);
$telegram->setLogPath($BOT_NAME.'.log');

(New!) Set verbosity to 3, to log also curl requests and responses from the bot to Telegram:, _(*60)

$telegram->setLogRequests(true);
$telegram->setLogPath($BOT_NAME.'.log');
$telegram->setLogVerbosity(3);     

This code is available on Github. Pull requests are welcome., _(*61)

Troubleshooting

If you like living on the edge, please report any bugs you find on the PHP Telegram Bot issues page., _(*62)

Contributing

See CONTRIBUTING.md for information., _(*63)

Credits

Credit list in CREDITS, _(*64)