Telegram Bot: Contributing

This guide tells you how to create a plugin for my Telegram Bot.

You can see the code on Github.

Forking the repository

To create a new plugin you should have basic knowledge of PHP and Git (you should be able to clone / fork the repository). To do so you should use the Git Bash for Windows or just install git on Linux.

Get a Github account an fork the repository of the Telegram Bot. Then clone it to your PC.

Creating a Plugin

To create a new Plugin, you should navigate to the plugins folder. This folder contains all plugins. Each plugin has its own folder with a unique name. You should now choose a short, precise name for your plugin, e.g. myplugin. Then create a folder with this name (lowercase).

Inside of this folder you have to create at least 2 files: aliases.php and plugin.php . You can create more files if you want or need them. To add multi-language support to you plugin, create another file with the name lang.json .

The folder structure should look like this:

|
| config.php
| plugins/
|--- myplugin/
|------ aliases.php
|------ plugin.php
|------ lang.json
|--- hello/
   . . .

The aliases.php registers your plugin to the system, the plugin.php does all the plugin logic and the lang.json contains multiple translations for your texts managed by a central “translator” class.

Language Files

You should add a lang.json to you plugin. Doing this, you can load your plugin into the translator class and use short names for strings. The translator will load the specific string in the chosen language if you have defined it. Otherwise it will use the default language (english – can be changed). This file is JSON and has a structure like this:

{
 "help0": {
 "en": "/help `plugin` - Displays the help page",
 "de": "/help - Zeigt die Hilfe an"
 },
 "help1": {
 "en": "/help `plugin` - Displays the help page for a specific plugin",
 "de": "/help `plugin` - Zeigt Hilfe eines bestimmten Plugins an"
 },
 "available": {
 "en": "Available Plugins",
 "de": "Verfügbare Plugins"
 },
 "notfound": {
 "en": "Plugin %s not found",
 "de": "Plugin %s nicht gefunden."
 },
 "helpheader": {
 "en": "Help for %s (Plugin: %s)",
 "de": "Hilfe für %s (Plugin: %s)"
 }
}

(This is the language file for the help plugin). You could add other languages as well.

You can access these language file in your code at any time:

global $t;
$t->setPlugin("myplugin");

// This returns the string in the active language
// E.g: Available Plugins
$t->g("available");

g is the shortform for get, t stands for Translator. You could also specify arrays – you find this in the hello plugin for example.

Register your plugin

There are up to 3 possible environments your plugin can be called (2 working for now):

  • A command directly for your plugin
  • A genereal listener – you have to handle every incoming message
  • Future: Cronjob

To use the first variant, you have to specify at least one alias. This needs to be done in the aliases.php . If you want to receive messages containing a specific command ( /mycmd ) you can do the following in the aliases.php:

global $pluginManager;

// This makes the bot call your plugin every time a message
// starting with /mycmd is found (only for textmessages)
$pluginManager->registerAlias("mycmd", "myplugin", "text");

// This calls your plugin every time a message of the specified type(s)
// is received (array of type or just one type)
// E.g.: text and location
$pluginManager->registerReceiver("myplugin", array("text", "location"));

// Add a help page
global $t;
$t->setPlugin("myplugin");

// Adds two lines of help from the lang.json
$helps = array(
    $t->g("help0"),
    $t->g("help1")
);
$pluginManager->addHelp("myplugin", $helps);

This peace of code will actually work, but you might want to look into other plugins for more options. E.g. you can add multiple aliases, if your plugin should offer multiple services or you just want to shorten a longer command.

Write your logic

After all the registration stuff is done, you can start writing the actual plugin.

This is a PHP class with at least one method, but for receiving all messages (if you called registerReceiver(…), you need another one. The plugin.php should look like this:

<?php
class MyPlugin {
    // This is called for every alias you registered
    public function execute($message) {
           
    }

    // This is called for every message of the type
    // you gave in registerReceiver("myplugin", {types})
    public function receive($message) {

    }
}
?>

Inside of these methods you can do whatever you like. You can also add other methods or include other files. The $message variable represents the received message. Please see this page for all attributes. You can access the attribute by using $message->attribute.

You also could modify the values, but this is only needed in few situations.

Additionally the $message offers three other attributes / functions:

  • getData() returns everything except the command from the message. This can be useful if you want to get additional parameters of your command.
  • getCommand() returns the actual command (without the / )
  • exploded returns an space-exploded version of the text

To make your commands clickable in Telegram even if you use parameters, your command may not contain an underscore. Underscores are used to separate parameters. E.g.:

/mycmd_param1_param2 data1 data2

will match the Alias command “mycmd”. The getCommand() will return “mycmd_param1_param2” (which can be exploded) and getData() will return “data1 data2”. In the messenger itself this will result in a clickable /mycmd_param1_param2.

 

Using the API

You cannot only receive messages, you also can send messages. Therefore you should use the global variable $api or the static methods of the API class. If you want to send a message (of type “text”) to the chat you received a message from you can use:

global $api;
// $md: Set to null for normal mode or to "Markdown" if you want
// your text to use basic markdown
$api->sendMessage($message->chat->id, $text, $md);

// Alternative:
Api::reply($message->chat, $chat, true/false);
                                // Markdown?

The $api object offers more functions to you like sendVideo() or sendPhoto().

These methods can be used with the video / photo data or a link to them.