{"id":16551008,"url":"https://github.com/mehdisadeghi/clashogram","last_synced_at":"2025-04-07T18:14:53.719Z","repository":{"id":23399498,"uuid":"93321333","full_name":"mehdisadeghi/clashogram","owner":"mehdisadeghi","description":"Clash of Clans war monitoring for telegram channels.","archived":false,"fork":false,"pushed_at":"2024-11-17T20:19:47.000Z","size":237,"stargazers_count":28,"open_issues_count":3,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-31T14:11:15.407Z","etag":null,"topics":["bot","clanwar","clash-of-clans","game","telegram"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mehdisadeghi.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-04T15:07:52.000Z","updated_at":"2024-12-18T07:25:23.000Z","dependencies_parsed_at":"2024-12-24T14:14:12.427Z","dependency_job_id":"59454018-e073-4913-8302-dfc841d93762","html_url":"https://github.com/mehdisadeghi/clashogram","commit_stats":{"total_commits":252,"total_committers":6,"mean_commits":42.0,"dds":0.06349206349206349,"last_synced_commit":"117b78a3043bdd036d80b30beb9ec9df366fb0e2"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mehdisadeghi%2Fclashogram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mehdisadeghi%2Fclashogram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mehdisadeghi%2Fclashogram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mehdisadeghi%2Fclashogram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mehdisadeghi","download_url":"https://codeload.github.com/mehdisadeghi/clashogram/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247704571,"owners_count":20982298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","clanwar","clash-of-clans","game","telegram"],"created_at":"2024-10-11T19:36:06.634Z","updated_at":"2025-04-07T18:14:53.694Z","avatar_url":"https://github.com/mehdisadeghi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. contents::\n   :depth: 3\n..\n\nclashogram |Build Status| |Build status| |Pypi status|\n======================================================\n\nClash of Clans war moniting for telegram channels.\n\n    NOTE: Clash of Clans API data is always 10 minutes behind the game\n    events. This is not a bug in this program.\n\n    NOTE: Your warlog must be public.\n\n``clashogram`` monitors your clan's warlog and posts the following\nmessages to a Telegram channel:\n\n1. Preparation started (with clans and players information)\n2. War started\n3. New attacks (with details)\n4. War over\n\nRequirements\n------------\n\nTo run the program you need to have python 3.3 or higher. You will also\nneed ``pip`` to install python dependencies. Moreover, using a\n`virtualenv \u003chttps://virtualenv.pypa.io/en/stable/\u003e`__ makes\ninstallation much easier, otherwise you have to install everything\nsystem-wide. On Linux you would need to run commands with ``sudo``, on\nwindows with administrator account.\n\nInstallation\n------------\n\nFrom pypi::\n\n    $ pip install clashogram\n\nFrom Github (for development)::\n\n    $ git clone https://github.com/mehdisadeghi/clashogram.git\n    $ cd clashogram\n    $ pip install flit\n    $ flit install --symlink\n\nWith Docker\n-----------\n\nIn order to run the latest docker version do the following::\n\n    $ docker run -it mehdisadeghi/clashogram:latest\n\nThis will prompt for the necessary parameters and start the app. Slighty better would be::\n\n    $ docker run --env-file=\u003cENV_FILE\u003e --name clashogram --restart=always -d mehdisadeghi/clashogram:latest\n\nThis will run the container in the background and restart it if it fails. ``ENV_FILE`` should contain one ``key=value`` per line (the app params). In my experience this works good enought, however for some reason sometimes docker does not start the container after reboot. In that case a systemd unit or similar could be used to start the ``clashogram`` container above.\n\nUsage\n-----\n\nIn order to use the program do the following:\n\n1. Open a Clash of Clans developer account at\n   https://developer.clashofclans.com/.\n2. Find your external IP address using a website like\n   `this \u003chttps://whatismyipaddress.com/\u003e`__.\n3. Go to your CoC developer page and create an API token for the IP number you just found.\n4. Create a Telegram bot using BotFather and copy its token.\n5. [For Channels] Create a new Telegram channel and add the bot you just created as to that channel. As of May 2020, bots can only be added as administrators to channels. If you want to post to a group instead of a channel see the instructions below.\n6. [For Groups] Add the bot you just created to your Telegram group (create one if necessary).\n\nObtaining The Chat ID\n~~~~~~~~~~~~~~~~~~~~~\nIn order to send messages to a channel or a chat in Telegram we need the ID of that chat, i.e. ``chat_id``. This is how Telegram API works. For public channels it is possible to use the name of the channel prefixed with ``@`` as ``chat_id``, e.g. ``@mypublicchannel``. However, for private channels and group chats we need to obtain the ``chat_id``.\n\nTake the following steps to obtain the correct ``chat_id``:\n\n1. Add the bot to the group or channel\n2. Make sure to write something in the channel/chat\n3. Use the ``bot_token`` from the step 4 of the previous section and run one of these this command::\n\n    # For a group chat run this\n    $ curl --silent --request POST https://api.telegram.org/bot\u003cYOUR_BOT_TOKEN\u003e/getUpdates | jq '.result | map(select(.message.chat.type == \"group\")) | .[0].message.chat.id'\n\n    # For a channel run this\n    $ curl --silent --request POST https://api.telegram.org/bot\u003cYOUR_BOT_TOKEN\u003e/getUpdates | jq '.result | map(select(.channel_post.chat.type == \"channel\")) | .[0].channel_post.chat.id'\n\nYou can omit the `jq \u003chttps://stedolan.github.io/jq/\u003e`__ part and just search for a ``type=group`` or ``type=channel`` in the output and take note of its ``id``. This is what we will use in the rest of this document as ``chat_id`` for channels and groups. Remember that you can also use ``@yourpublicchannel`` form as ``chat_id`` for public channels.\n\nNow to make sure if the ``chat_id`` realy points to a chat, run the following command and see whether your bot can post to your channel or group chat::\n\n    $ curl --request POST --url https://api.telegram.org/bot\u003cYOUR_BOT_TOKEN\u003e/sendMessage\\?chat_id\\=\u003cCHAT_ID_FROM_THE_PREVIOUS_STEP\u003e\\\u0026text\\=hi\n\nIf it does not work, make sure you have done the previous steps correctly or open an issue on GitHub.\n\nStarting The Program\n~~~~~~~~~~~~~~~~~~~~\n\nNow we can proceed with starting the program. Run the following command to install and start the program::\n\n    $ pip install clashogram\n    $ clashogram --coc-token \u003cCOC_API_TOKEN\u003e --clan-tag \u003cCLAN_TAG\u003e --bot-token \u003cTELEGRAM_BOT_TOKEN\u003e --chat-id \u003cCHAT_ID\u003e --forever\n\n    NOTE: Remember that channel names begin with ``@`` and chat_ids are numbers (often negative).\n\n\nIf you don't want attack updates in your channel add ``--mute-attacks`` to the above command.\n\nIn order to have messages in a different locale do the following and\nthen run the program::\n\n    $ export LANGUAGE=\u003cLANGUAGE_CODE\u003e\n    # This is for Persian\n    $ export LANGUAGE=fa\n\nOr do it in one step::\n\n    $ LANGUAGE=fa clashogram --coc-token \u003cCOC_API_TOKEN\u003e --clan-tag \u003cCLAN_TAG\u003e --bot-token \u003cTELEGRAM_BOT_TOKEN\u003e --chat-id \u003cCHAT_ID\u003e\n\nSetting Language on Windows\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\nMake sure to run ``set LANGUAGE=\u003cyour_lang_code_here\u003e`` on windows before running the program.\n\nRun as a service\n~~~~~~~~~~~~~~~~\n\nThe simplest way to use Clashogram is leave it running in background\nusing either `byobu \u003cbyobu.org\u003e`__ or `GNU\nScreen \u003chttps://www.gnu.org/software/screen/\u003e`__. Another solution is to\ninstall a systemd unit::\n\n    [Unit]\n    Description=Clashogram Daemon\n    After=network.target\n\n    [Service]\n    WorkingDirectory=/path/to/clashogram/\n    EnvironmentFile=/path/to/env/file\n    ExecStart=/path/to/python /path/to/clashogram\n    Restart=on-failure\n    User=someuser\n\n    [Install]\n    WantedBy=multi-user.target\n\nSearch internet for more information on installing systemd units on your\nOS.\n\nContribution (PRs welcome!)\n---------------------------\n\nThe Telegram notification is isolated from the rest of the program. You\ncan replace it with anything else to have your messages sent to\nsomewhere else.\n\nFork and clone the repository and send a PR. Make sure tests pass\nbeforehand::\n\n    python -m unittest discover\n\nOr with ``py.test``::\n\n    pip install pytest\n    py.test tests.py\n\nI18N\n----\n\nIn order toadd or update a new language catalog do the following::\n\n    pip install babel # Install the babel i18n tool first.\n\n::\n\n    pybabel init -i clashogram/locales/messages.pot -d clashogram/locales -l \u003cLANGUAGE_CODE\u003e\n    pybabel update -i clashogram/locales/messages.pot -d clashogram/locales -l \u003cLANGUAGE_CODE\u003e\n\nFor example::\n\n    pybabel init -i clashogram/locales/messages.pot -d clashogram/locales -l fa\n    pybabel update -i clashogram/locales/messages.pot -d clashogram/locales -l fa\n\nIn case of adding new messages extract them and compile again::\n\n    pybabel extract clashogram/ -o clashogram/locales/messages.pot --project Clashogram --version 0.6.0\n    pybabel update -i clashogram/locales/messages.pot -d clashogram/locales\n    pybabel compile -d clashogram/locales\n\nFor more information on internationalization see\n`Babel \u003chttp://babel.pocoo.org/en/latest/setup.html\u003e`__.\n\nCredits\n-------\nThanks Ali Ayatollahi and other members from IRAN clan (tag #YVL0C8UY) for the initial idea and testing.\n\n\nLicense\n-------\n\nMIT\n\n.. |Build Status| image:: https://travis-ci.org/mehdisadeghi/clashogram.svg?branch=master\n   :target: https://travis-ci.org/mehdisadeghi/clashogram\n.. |Build status| image:: https://ci.appveyor.com/api/projects/status/ovixrhmsp3og4nt4/branch/master?svg=true\n   :target: https://ci.appveyor.com/project/mehdisadeghi/clashogram/branch/master\n.. |Pypi status| image:: https://img.shields.io/pypi/v/clashogram.svg\n   :target: https://pypi.python.org/pypi/clashogram\n\n\nRussian Translations\n--------------------\nYou can read this document in Russian thanks to Timur from Illuminati clan. Thanks Timur!\n`this document in Russian \u003cREADME_RU.rst\u003e`__\n\n\nراهنمای فارسی\n-------------\nبرای مطالعه راهنمای فارسی به `این آدرس \u003chttp://mehdix.ir/clashogram.html\u003e`__ سر بزنید.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmehdisadeghi%2Fclashogram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmehdisadeghi%2Fclashogram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmehdisadeghi%2Fclashogram/lists"}