### 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.py`which 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.
#### 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>/dispatche
```
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.