Skip to main content

Clash of Clans war moniting for telegram channels.

Project description

clashogram Build Status Build status Pypi status

Clash of Clans war moniting for telegram channels.

NOTE: Clash of Clans API data is always 10 minutes behind the game events. This is not a bug in this program.

clashogram monitors your clan’s warlog and posts the following messages to a Telegram channel:

  1. Preparation started (with clans and players information)
  2. War started
  3. New attacks (with details)
  4. War over


To run the program you need to have python 3.3 or higher. You will also need pip to install python dependencies. Moreover, using a virtualenv makes installation much easier, otherwise you have to install everything system-wide. On Linux you would need to run commands with sudo, on windows with administrator account.


From pypi:

pip install clashogram

From Github:

git clone
cd clashogram
install -r requirements.txt flit
flit install --symlink


In order to use the program do the following:

  1. Open a Clash of Clans developer account at
  2. Find your external IP address using a website like this.
  3. Go to your CoC developer page and create an API token for the IP number you just found.
  4. Create a Telegram bot using BotFather and copy its token.
  5. Create a new Telegram group and add the bot you just created as an administrator to that group.

Now you can run the following command:

pip install clashogram --coc-token <COC_API_TOKEN> --clan-tag <CLAN_TAG> --bot-token <TELEGRAM_BOT_TOKEN> --channel-name <TELEGRAM_CHANNEL_NAME> --forever

If you don’t want attack updates in your channel add –mute-attacks to the above command.

In order to have messages in a different locale do the following and then run the program:

export LANGUAGE=fa

Or do it in one step:

LANGUAGE=fa --coc-token <COC_API_TOKEN> --clan-tag <CLAN_TAG> --bot-token <TELEGRAM_BOT_TOKEN> --channel-name <TELEGRAM_CHANNEL_NAME>

Setting Language on Windows

Make sure to run set LANGUAGE=<your_lang_code_here> on windows before running the program.

Run as a service

The simplest way to use Clashogram is leave it running in background using either byobu or GNU Screen. Another solution is to install a systemd unit:

Description=Clashogram Daemon

ExecStart=/path/to/python /path/to/


Search internet for more information on installing systemd units on your OS.

Contribution (PRs welcome!)

The Telegram notification is isolated from the rest of the program. You can replace it with anything else to have your messages sent to somewhere else.

Fork and clone the repository and send a PR. Make sure tests pass beforehand:

python -m unittest discover

Or with py.test:

pip install pytest


In order toadd or update a new language catalog do the following:

pip install babel # Install the babel i18n tool first.
pybable init -i clashogram/locales/messages.pot -d clashogram/locales -l <LANGUAGE_CODE>
pybable update -i clashogram/locales/messages.pot -d clashogram/locales -l <LANGUAGE_CODE>

For example:

pybable init -i clashogram/locales/messages.pot -d clashogram/locales -l fa
pybable update -i clashogram/locales/messages.pot -d clashogram/locales -l fa

In case of adding new messages extract them and compile again:

pybabel extract clashogram/ -o clashogram/locales/messages.pot --project Clashogram --version 0.6.0
pybabel update -i clashogram/locales/messages.pot -d clashogram/locales
pybabel compile -d clashogram/locales

For more information on internationalization see Babel.


Thanks Ali Ayatollahi and other members from IRAN clan (tag #YVL0C8UY) for the initial idea and testing.



Russian Translations

You can read this document in Russian thanks to Timur from Illuminati clan. Thanks Timur! this document in Russian

راهنمای فارسی

برای مطالعه راهنمای فارسی به این آدرس سر بزنید.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for clashogram, version 0.7.0
Filename, size File type Python version Upload date Hashes
Filename, size clashogram-0.7.0-py3-none-any.whl (53.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size clashogram-0.7.0.tar.gz (38.5 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page