No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



YeenBot is a simple Telegram bot written in Node.Js and utilizing

Bot is modular via plugins.

Current plugins:


YeenBot uses grunt as its build/run system. Install grunt first via npm install -g grunt to install the global instance of grunt, then you can use npm install in the YeenBot directory to install all of its dependencies.

Currently uses lodash, bluebird (for JS promise wrappers), node-telegram-bot-api, winston for multi-transport logging, and ector for the chatbot.

Once installed, you can use grunt bot (or just grunt by itself) to actually run the bot. But this requires configuring first. By default the bot is named yeen_bot, but you will need to change this to something unique for you. Just edit the gruntfile.js or you can use grunt bot:name_of_your_bot to override on a per-use case basis.

Other supported commands:

  • grunt watch to perform live watching of YeenBot source files, with automatic jshint as needed.
  • grunt tests to run the Mocha-based tests for YeenBot.


To configure YeenBot, edit the file called config/botname_config.json. (Where, botname, of course is the Telegram username of your bot.) This contains the configuration information about the bot. This is read-only information which is loaded only during the bot's loading phase.

There is an example configuration present in config/yourbot_example.config.json for reference.

For each bot, create an object with the same Telegram username of your bot. Some explanation of the options:

  • msgs_per_minute is a global option for all bots. It lets you throttle your bot, 1500 msgs/min is below the 1800 msgs/min that Telegram allows.
  • token is the secret token used for your bot to authenticate to Telegram.
  • admins is an array of userids for people who are to be administrators.

You can reload this JSON information into the bot by issuing a /reboot command.


By default, the bot will write all logging information to the console.

It also creates a file called botname.log in the data directory which contains log entries in JSON.

Built-in Commands

Some commands are native to the bot and require no plugins to function. They are:

  • /start - This just returns /help.
  • /help - Help text for the bot.
  • /info - Basic information about the bot, such as version number and source code location.
  • /whoami - Returns information about the user who invokes this command.
  • /plugins - Lists all available plugins. In the future, you will be able to enable/disable/reload plugins. ADMIN
  • /learn - Adds a group that this command is issued in, into the group cache. Required for some plugin commands. ADMIN
  • /reboot - Reboots the bot. ADMIN

Commands with ADMIN can only be executed by an admin.


Most of the functionality of YeenBot is expressed through plugins. They live under lib/plugins and it is usually one file per plugin. You will need to load a plugin via YeenBot.registerPlugin in order for it to become active.

Plugins are classes and must register at least two methods: getHelpText, which returns the help text seen when the user performs a /help command for the bot, and destroy which will unload the bot.

Aside from that, plugins are allowed to register whatever functionality they need. They are given just one object: The Bot itself, which contains the Telegram API code under botapi and the JSON database system under config_db and data_db. Use data_db to store any plugin-related information.

For command-based plugins, you should register a cmd_yourcmdname event listener on the bot, which will be passed any space-delimited options plus a copy of the Telegram message structure that triggered the command. Be sure to de-register any listens (either on YeenBot or the botapi) in your destroy method!


Welcomer will welcome people who join any groups that have been learned by YeenBot.

To use, first invite YeenBot to a group. Then, issue the /learn command in that chat. YeenBot will register the group with its cache.

From there, issue the /welcomer command to invoke the menu for managing groups to welcome. You can:

  • list - List all groups that the bot is set to welcome for.
  • register - Register a group to YeenBot so it will start welcoming people who join that group.
  • remove - Remove a group that YeenBot has been set to welcome for.
  • view greeting - Preview the greeting that YeenBot uses.
  • set greeting - Set a greeting for YeenBot to use.

Note that by default, greetings are in Markdown format. As of yet, YeenBot does not have the ability to read Markdown from a user's message. (It seems Telegram strips this out automatically from the client.) So if you want to use Markdown you will need to edit the greeting directly in the botdata.json file.


This plugin simple rolls dice. It works both for private messages and group chat.

The format for the command is /roll 2d4, which tells YeenBot to roll two 4-sided dice. Note that YeenBot will cap the number of dice to 20 and the sides of the dice to 1000.

If you use /roll by itself, YeenBot will ask you (via menus) what you want to roll.

You can also roll single dice such as /roll d20. Dice rolls that are given in a group chat must be in the format of /roll YdX or /roll dX. Group dice rolling does not support the menu mode (ie: not passing the dice to roll).


This plugin is a simple system which will inject messages straight into YeenBot's internals. Used only for testing.


A simple chatbot plugin. TODO.