Assuming you are using Telegram actively for notifications and to control HA’s appliances, you may want to know as soon as possible if Telegram API is not available and your bot is out of operation. Even if you are not a “happy” citizen of a country who is trying to block access to it.
The post also assumes that you know how to create a Telegram bot and get API tokens to control it.
Create Telegram API sensor
We want to create a simple bash script which will give us the current status of Telegram API:
if curl --silent --fail -m 5 -o /dev/null -G https://api.telegram.org/botXXXXX:YYYYY/getMe; then echo online else echo offline fi
XXXXX:YYYYY - is an API token, provided by Telegram BotFather. To check if it works just issue this command in a Linux prompt:
If everything is good, you should get the
If your Telegram setup requires Socks Proxy to work, you can add it to the curl command like that:
curl --silent --fail -m 5 -o /dev/null -G -x socks5://ip:port https://api.telegram.org/botXXXXX:YYYYY/getMe
and with authentication:
curl --silent --fail -m 5 -o /dev/null -G -x socks5://login:password@ip:port https://api.telegram.org/botXXXXX:YYYYY/getMe
Install script in Hass.io
Now we should figure out where we want to copy our script within Hass.io. I suggest to create a
scripts folder within your regular Home Assistant
config directory and copy our script there. This should work fine both in Hass.io and hassos. One more benefit - we can edit our scripts in the same way we do it with Home Assistant configuration files.
Create a sensor
Add the following lines to the
sensors: section of
- platform: command_line name: "Telegram Status" command: sh /config/scripts/telegram_health.sh
Open entity list by clicking on the <> icon and type telegram in the entity filter field and you should see your sensor up and running:
To test if it works, you can modify
telegram_health.sh file so that it contains wrong credentials, e.g. change API token. The status should change to
offline within a minute:
Create a notification
For obvious reasons, it is not a very good idea to use Telegram to notify if its API is out of order so we have to choose another channel of communication. I decided to stick to html5 push notifications which work fine with Android devices and Windows PCs but is not supported by iOS devices yet.
I will not recount the configuration quest, which includes a domain confirmation step besides others, but, it seems, it was worth it. Now any device with Chrome or Firefox browser is able to receive these notifications and display them in a nice way. You only need to enable push notifications settings in Home Assistant Web UI running on this device:
Talking about an Android device, you may close your browser and still receive a notification, which is good. Google says that it should work similarly on Windows PCs if you install at least one browser extension with ‘background’ permission. I did not check that since my browser is always open anyway.
Let’s create a couple of automations which will send a notification to all our devices when Telegram API is unavailable and (sic!), we will dismiss the previously sent notification in case if the connecivity restored.
- id: '1559835053687' alias: Telegram is down trigger: - entity_id: sensor.telegram_status platform: state from: online to: offline condition:  action: - data: message: Telegram API is down! data: tag: telegram_down service: notify.homeassistant - id: '1559835053688' alias: Telegram is up trigger: - entity_id: sensor.telegram_status platform: state from: offline to: online condition:  action: - data: data: tag: telegram_down service: notify.html5_dismiss
Here we use a special
tag property which allows us to control a specific notification which was sent before. For instance, we can close it or change its text.
This is how notification looks like:
It is relatively easy to build the Telegram API Health sensor. I should stress it will not detect failures of your bot or Home Assistant components running this bot, this is for Telegram API only. Obviously, html5 push technology has its own pros and cons, so you can choose another way of communication. It only remains for me to wish it will never be any need for it.