YeenBot is a simple Telegram bot written in Node.Js and utilizing https://github.com/yagop/node-telegram-bot-api
Bot is modular via plugins.
- WelcomerPlugin for greeting people in a group chat.
- ChatterPlugin for a simple chat-bot.
- DiceRollerPlugin for rolling dice, either in group chat or private messages.
- MessageTesterPlugin for injecting messages straight into YeenBot's core, for tests.
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 watchto perform live watching of YeenBot source files, with automatic jshint as needed.
grunt teststo 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_minuteis a global option for all bots. It lets you throttle your bot, 1500 msgs/min is below the 1800 msgs/min that Telegram allows.
tokenis the secret token used for your bot to authenticate to Telegram.
adminsis an array of userids for people who are to be administrators.
You can reload this JSON information into the bot by issuing a
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.
Some commands are native to the bot and require no plugins to function. They are:
/start- This just returns
/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
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
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
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.