Telegram-alert, a Telegram-based notification service

From time to time it happens I have to run a simulation that takes more than a few hours to run. Not knowing in advance when the simulation is finished and the results are available, I either frantically check every half hour to see if it is done, or forget about it until hours later. Both situations are less than ideal, so last week I wrote a script that allows me to send notifications from the shell to my phone, using a Telegram bot.

Telegram is a messaging app available for both desktop and mobile that, apart from a slew of other nice features, allows anyone to create bots, interfaces that can pass user input to any backend and reply with messages.

With the help of a bot, getting my phone to buzz after a long running simulation is as easy as


Having such a tool in bash allows for easy integration in other scripts and makes it portable. The minimal dependencies means it runs on server environments as well, without requiring any permissions to install outside packages.

Moreover, setting up a Telegram bot is a 3-minute process and can be done from within Telegram.

The tool is hosted on GitHub. You can clone it and run it as

git clone
cd telegram-alert

and copy the file alert somewhere on your $PATH (like /usr/local/bin or ~/.local/bin) so it is accessible everywhere.


The tool is designed to have minimal external dependencies. It requires only

all of which should be present on standard Mac and Linux systems, but can otherwise be installed with brew/any package manager.

The script also requires a Telegram bot to notify you with. Setting one up is easy and can be done through Telegram itself with the BotFather wizard.


  1. If you haven’t already, download Telegram on your (mobile) device.
  2. Setup a Telegram bot. Pick any name you like.
  3. Start a conversation with your new Telegram bot.
  4. Clone this repository or download the file alert and put it somewhere in your PATH (like in ~/.local/.bin).


The first time you run alert, it asks for a token. You can find this token in your conversation with the BotFather. It looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 and if you supply it to the script, it will be stored in the file ~/.telegram_alert.conf for future use.

Keep the token private, it acts like a password to your bot.

After obtaining the token, it will fetch the chat ID of the conversation you started with the bot. Upon success, this ID will also be stored in ~/.telegram_alert.conf. If you have not conversed with the bot, it will not be able to find this chat ID.

If something weird happens, deleting/modifying the configuration file might help.


No information is stored/transmitted through any other third parties than your own and the Telegram servers. You can examine the script to convince yourself of this.

However, even though communication through between you and a Bot is private and encrypted (as long as you keep you token safe), the bots themselves are public, meaning anyone can start a conversation with your bot. For this reason, the first time after a chat ID is fetched and set, alert displays the username with which the connection has been established. Obviously, this will also be confirmed by your bot sending you a message.

Alternatively, you can hardcode/preset the chat ID in ~/.telegram_alert.conf.

As long as a connection is established and the chat ID is functional, all messages to the bot will be ignored.


Any suggestions and bug reports are welcome!