Datamachine studios has developed telegram-pybot which is a beautiful, plugins based (similar to Yago's Lua based telegram-bot) Python bot.

You can read an introduction about it on my blog.


Now that we have a Python bot framework there is no more an excuse to not write your own Jacondas or Anacondas or what not?

Below, I shall put together a small high level overview of all that needs to be understood so that one can directly jump into building plugins for telegram-pybot and enjoy it in group chats. For all the low level details, it is preferrable to read the linked code, source, or docs.

The chain

All useful interaction with any bot is a long chain of calls between different programs. It is fun to think of the actual physical connection and the software connection. Just for that fun:

The Setup

This is the most difficult part or the easiest part depending on what you've been doing with your computer in your life. Here are the essentials required:


Assuming you've all that handy, you can follow the instructions in the readme of telegram-pybot to clone itself, clone tg, configure and make tg, and even launch the bot.


This is probably the first biggest hurdle


If you've never used tg-cli you'll be asked to enter your phone number. And the input won't work because the bot runs in a subprocess.

Just do this

cd tg

enter your alternate phone number, verification code, and then

cd ..


If you have used tg-cli with your primary number once, the bot'll start running in that. And when I tried last night it wasn't able to respond to its own commands.

tg-cli comes with an excellent way to run multiple profiles. Profiles are defined in a config file.

By default, the ~/.telegram-cli folder is used as the directory to save authentication info. There's a config file created in this folder automatically.

Delete the ~/.telegram-cli folder, and follow #newhere steps to register your alternate number.

Later if you want to use your primary number, just create a new profile using ~/.telegram-cli/config and use -p switch while running bin/telegram-cli to choose that profile.


./ is our command to run the bot. It'll take care of everything.


There is very little configuration to be done. In permissions.conf, admins = 0 should become admins = 1234567 if 1234567 is your Telegram user id. You can use tg-cli to find out your user id with the command user_info YourName

Plugin Management

Plugin management is best done via a Telegram chat itself. Once you have added yourself as an admin, you will be authorized to use the PluginManager plugin and !pkg update will sync the plugin list. pkg install dice will install the dice plugin and so on.

Writing your own plugin

This is the most interesting part.

Plugin folder structure

For the sake of avoiding git, maintaining plugin repo, etc, we will build plugins directly inside the plugins folder inside telegram-pybot. If you are interested to see how an advanced plugin would look like, checkout the folder structure of spyfall

Sample plugin

Use the echo plugin in plugins folder to base your work on. Let's call our new plugin "ping-pong".

cp echo.plugin pingpong.plugin

pingpong.plugin contains metadata about the plugin. Name and Module info are important in it. Change it to PingPong and pingpong respectively. contains the basics of a plugin. Read the comments beneath to see what each line in this file does. The new function of our plugin is to respond with pong when someone says /ping.

import plugintypes

import plugintypes module so that we can subclass TelegramPlugin.

class PingPongPlugin(plugintypes.TelegramPlugin):

define a class called PingPongPlugin which's a subclass of TelegramPlugin

    Just say pong when someone says ping

This is just a docstring for developers

    patterns = [

define the patterns that need to be captured by the plugin. This does a regex matching and we will talk about matching later. ^ refers to the beginning of a line and $ refers to the end of a line.

    usage = [
        "/ping: pongs",

This is the string that is shown when someone says !help PingPong

    def run(self, msg, matches):

this is the function that'll run if our pattern matches. msg is the object that has all the information about the message that matched. matches is a python object that is the result of the match, it can be used to access the text that matched. We can ignore it now.

        return "pong"

whatever is returned is send as a message back to the user. In this case, pong

Make this plugin seen

To enable this plugin we can manually edit plugins.conf file and add ;;PingPong to the default_plugins_to_load list. Then launch the bot.

Pattern matching

Pattern matching is an brain twister. Read Python docs of re module to know how this works.


Plugins are even more fun when you can effectively use git to keep your plugin updated and curate plugins in a repository. Checkout telegram-pybot-emoticons to see a simple sample plugin structure.
The plugin repository structure can be seen here. Although, a word of caution, there's a very good chance that this architecture will be overhauled soon.


This page goes through an iterative write-feedback-improve cycle. Please give me ideas of how to improve this page.