======================
A Telegram Bot based on the official Telegram Bot API
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 supports Reply Markup and handle commands in group chat with multiple bot.
-
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 tobotfather
. -
@botfather replies with
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
-
Type whatever name you want for your bot.
-
@botfather replies with
Good. Now let's choose a username for your bot. It must end in
bot. Like this, for example: TetrisBot or tetris_bot.
-
Type whatever username you want for your bot, minimum 5 characters, and must end with
bot
. For example:telesample_bot
-
@botfather replies with:
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.
Use this token to access the HTTP API: 123456789:AAG90e14-0f8-40183D-18491dDE
For a description of the Bot API, see this page: https://core.telegram.org/bots/api
-
Note down the 'token' mentioned above.
-
Type
/setprivacy
to @botfather. -
@botfather replies with
Choose a bot to change group messages settings.
-
Type
@telesample_bot
(change to the username you set at step 5 above, but start it with@
) -
@botfather replies with
'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
-
Type
Disable
to let your bot receive all messages sent to a group. This step is up to you actually. -
@botfather replies with
Success! The new status is: DISABLED. /help
You need server with https and composer support.
Install this package through Composer. Edit your project's composer.json
file to require longman/telegram-bot
.
Create composer.json file:
{
"name": "yourproject/yourproject",
"type": "project",
"require": {
"php": ">=5.4.0",
"longman/telegram-bot": "*"
}
}
And run composer update
Or run a command in your command line:
composer require longman/telegram-bot
You will notice that the Telegram Bot wants a value for API_KEY
. This token may be obtained via a telegram client for your bot. See this link if you are unsure of how to so this.
You must set a WebHook
Create set.php and put into it:
<?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);
// set webhook
echo $telegram->setWebHook('https://yourdomain/yourpath_to_hook.php');
} catch (Longman\TelegramBot\Exception\TelegramException $e) {
echo $e->getMessage();
}
And open your set.php via browser
After create hook.php and put:
<?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);
// here you can set some command specified parameters, for example, google geocode/timezone api key for date command:
$telegram->setCommandConfig('date', array('google_api_key'=>'your_google_api_key_here'));
// handle telegram webhook request
$telegram->handle();
} catch (Longman\TelegramBot\Exception\TelegramException $e) {
// log telegram errors
// echo $e->getMessage();
}
##MySQL storage If you want insert in database messages/users for further usage in commands, create database and import structure.sql and enable mysql support after object creation and BEFORE handle method
<?php
$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:
$telegram->enableMySQL($credentials, $BOT_NAME.'_');
##Commands The bot is able to recognise commands in chat with multiple bot. It can execute command triggering a chat event. Here's the list:
- 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 lets you handle commands that don't exist or to use commands as a variable: Favourite colour? /black, /red Favourite number? /1, /134
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:
$COMMANDS_FOLDER = __DIR__.'/Commands/';
$telegram->addCommandsPath($COMMANDS_FOLDER);
##Admin Commands (new!) Enabling this feature, the admin bot can perform some super user command like send message to all. You can specify one or more admin with this option:
$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.
##Send message to all active chats To do this you have to enable the mysql connection. Here's an example of use:
$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
);
print_r($results);
##Utilis You can also log incoming messages on a text file, set this option with the methods:
$telegram->setLogRequests(true);
$telegram->setLogPath($BOT_NAME.'.log');
This code is available on Github. Pull requests are welcome.
##Troubleshooting
If you like living on the edge, please report any bugs you find on the PHP Telegram Bot issues page.
##Contributing
See CONTRIBUTING.md for information.
Credit list in CREDITS