Telegram API Health Check for Hass.io

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

Where XXXXX:YYYYY - is an API token, provided by Telegram BotFather. To check if it works just issue this command in a Linux prompt:

sh telegram_health.sh

If everything is good, you should get the online response.

Socks Proxy

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 configuration.yaml :

- platform: command_line
  name: "Telegram Status"
  command: sh /config/scripts/telegram_health.sh

Test it

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:

1559841031905

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:

1559840956560

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:

1559841318857

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:

1559842086244

Conclusion

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.