Skip to content
War has started, on Twitter
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.

Bloomgogo War Bot

Created by Miguel Ángel Fernández Gutiérrez ·


Bloomgogo War Bot is a Twitter and Telegram bot that makes it easy to create live battles between Twitter users; it consists of:

  • A Telegram bot that serves as an admin, for an authorized user to control all the characteristics of the came.
  • A Twitter client that automatically extracts information and posts tweets to Twitter, based on the settings specified by the client.

The War

The war consists on battles between users, the last one to be alive is the winner!

First, we have to consider two types of "users":

  • Candidates: Twitter users that are not yet "warriors" or "users", they can opt-in the candidates list. Then, the admin can promote them to users.
  • Users: are the ones who fight in battles.

The admin can control the following features:

  • Battle scheduling: there is a scheduling system to program battles based on battle frequencies, dates, etc.
  • Opt-in: Twitter users can automatically enter to the candidates list if the opt-in option is enabled, by simply mentioning the bot's Twitter username in a tweet.
  • New user announce: new users can be announced to the Twitter's bot account, either natively or for certain users.
  • Battle updates: the app has a system to post tweets with images and lists to Twitter, to mantain the bot's user base updated about the war.


Right now, a documentation site is being built on Bloomgogo. For now, you can consult the documentation in the individual Python folders. Every method, class and variable is thoroughly documented.

File structure

Name Description
bots Contains two scripts, one for each bot
├── Telegram bot
└── Twitter bot
database Contains database files
└── warbot_db.json TinyDB JSON database. This can be modified in
lib Contains app's classes and modules
├── WarBotAdmin
├── WarBotAPI
├── WarBotDB
├── WarBotImageHandler
├── TelegramInterface
├── WarBotTwitter
├── Contains environment variables
└── WarBot
logs We recommend storing the logs here
resources Contains resources for image generating, also this app's logo
tmp Folder where the images generated will be stored temporarily

Class structure

Name Description File
TelegramInterface This module interacts directly with the Telegram API lib/
WarBot Main controller for Bloomgogo War Bot lib/
WarBotAdmin This module interacts with the Telegram bot lib/
WarBotAPI This module interacts with the Twitter API lib/
WarBotImageHandler This module generates images lib/
WarBotDB This module controls the database, in TinyDB lib/
WarBotTwitter This module interacts with WarBotAPI to deliver messages to Twitter lib/

How to set up the bot

The bot can be set up by executing the scripts and simultaneously. This functionality has been shortcut, and you can simply execute the warbot module:

python -m warbot

To execute it, this way, you must be located on this repo's main folder, having the folder warbot listed by ls (to clarify).

Please refer to requirements for more information on the libraries and versions that have been tested.

Setting up variables

The file contains an amount of variables that control the bot. You can generate them by making a Twitter app and starting a Telegram bot.

  • Make a Twitter app. You will need a Twitter Developers account. More information can be found on the Twitter Developers website.

    NOTE: the only permissions needed are read and write, no direct message functionality is yet used in this bot.

  • Start a Telegram bot. This can be easily done using Telegram's Bot Father. Start a conversation with @botfather on Telegram and simply go along!

Some things for Bot Father

Telegram bots incorporate the useful functionality of shortcutting the commands by integrating them in the Telegram app's GUI. To do this, you have to talk to Bot Father using the command /setcommands, selecting your bot and then sending it the following message:

help - Show help
runoptin - Enable opt-in
stopoptin - Disable opt-in
nextbattle - Next battle info
schedulebattle - Schedule next battle
battlefrequency - Battle frequency
setbattlefrequency - Set frequency
stopfrequency - Ignore frequency
forcebattle - Force battle
getfighters - Get all fighters
getfighter - Info about a fighter
getcandidates - Get all candidates
addfighter - Add fighter
deletefighter - Delete fighter
addcandidate - Add candidate
deletecandidate - Delete candidate
revive - Revive fighter
announcefighters - Automatically announce fighters
stopannouncefighters - Do not automatically announce fighters
status - Bot status
restart - Restart database

Of course, the information is scarce, but do not hesitate to use the /help command for more detailed info.


These are the libraries used under testing. You can create a virtual environment to use these versions. View pip and virtualenv's documentation for more info.


This project has been executed in Python 3.6.


This project could not have been created without the help of the following libraries, and the communities that have created them and actively mantain them:

  • Tweepy, a library for communicating with Twitter's API.
  • TinyDB, a minimal database.
  • Pillow, un fork de PIL (Python Image Library).

Of course, I also highly credit and thank the authors and mantainers of the rest of the libraries used. However, I have thought appropiate to specially mention these as they are a core part of this app's programming.

You can’t perform that action at this time.