What is it?

An automated bot for sending out announcements to selected Telegram group chat.

Why is it useful?

Can be handy for hackathons, etc., or any event that uses Telegram as a communication channel and need to send out announcements at specified times.

What do I need to use it?

Clone the code in the github repo below, add your announcements in the given yaml file, create a Telegram bot, add it in the Telegram chat you want it to publish and schedule how often the bot will run.

Repo & Code

Repo is https://github.com/wmhack2023/wmhack2023.github.io and the Telegram bot is in folder _telegram.

Scheduled announcements are store in _telegram/announcements.yaml. A typical announcement is a key:value pair, eg:

19/05/2023 09:15:00:
    - "Wikimedia Hackathon 2023 Registration still open at Technopolis, Machineworks building\n
Check venue here: https://www.mediawiki.org/wiki/Wikimedia_Hackathon_2023/Venue"

Key is the time of event, It will appear in the Telegram announcement, only trimmed to time and formatted as %H:%M.
If multiple events need to scheduled concurrently, prefer to specify them in a single value, eg separated by \n\n as Telegram might consider multiple concurrent posts as DoS attempt and block them.
Announcements are sent out 15 minutes prior to the defined time; this is controlled by ANNOUNCE_EVERY in _telegram/announcements.pywhich you can modify.

The bot script needs two environment variables.

• TOKEN This is the bot token that you are proved by the Telegram BotFather when you create your bot.
• CHAT_ID You get this ID *after* adding your bot to the Telegram chat where it should post by using url: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates (Credit: https://stackoverflow.com/questions/32423837/telegram-bot-how-to-get-a-group-chat-id)

On GitHub, store these values as repo secrets. On your laptop store them in an .env file.

Ηow to store secret variables in a GitHub Repo:

The process to store the required data from the script in secret format is as follows:

• Go to your repository that includes the _telegram directory and the script.
• Select the Settings tab from the top bar.
• Select the Secrets and Variables and the Actions tab.
• Create a new Secret Repository.
• In the input field of the tab, enter Name as "TOKEN" and in the Secret tab, enter the token generated by the Telegram API.
• Finally, the above process needs to be repeated for the Chat_ID tab, following the guidelines that are provided in the description.

Automation

In order to have a bot that runs autonomously there is a .github/workflows/announce.yml Github action in the repo above. As it is, it runs when triggered by an event. In order to be able to trigger this event programmatically (=automate triggering) you need to get a token from: https://github.com/settings/profile > Settings > Developer settings > Personal access tokens > Fine-grained tokens and create a token with Read access to metadata and Read and Write access to code and workflows.
Test the token and event triggering by running in a terminal:

curl -H "Accept: application/vnd.github.everest-preview+json" -H "Authorization: token <YOUR PERSONAL ACCESS TOKEN>" --request POST --data '{"event_type": "do_announce"}' https://api.github.com/repos/<YOUR_GITHUB_NAME>/<YOUR_REPO>/dispatches

If the above command successfully triggers the event (and thus bot execution), all you need is to schedule this trigger to run on a scheduled program.
In Wikimedia Hackathon 2023 a linux machine that what 24/7 on was used on which the following cron task was set up:

1/15 * * * * curl -H "Accept: application/vnd.github.everest-preview+json" -H "Authorization: token <YOUR PERSONAL ACCESS TOKEN>" --request POST --data '{"event_type": "do_announce"}' https://api.github.com/repos/<YOUR_GITHUB_NAME>/<YOUR_REPO>/dispatches

This task runs every 15 minutes, starting each hour at minute 01.

Feel free to change how you trigger this Github Action by adapting lines 03-05 in .github/workflows/announce.yml file. Beware that you can use Github's own cron scheduling (lines 06-07 in .github/workflows/announce.yml) but the scheduler might be off by several minutes, due to workload, thus some announcements might not trigger in time, or even not at all.