Telegram API Health Check for

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; then
    echo online
    echo offline

Where 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 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

and with authentication:

curl --silent --fail -m 5 -o /dev/null -G  -x socks5://login:password@ip:port 

Install script in

Now we should figure out where we want to copy our script within 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 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/

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:


To test if it works, you can modify 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
  - entity_id: sensor.telegram_status
    platform: state
    from: online
    to: offline
    condition: []
  - data:
    message: Telegram API is down!
      tag: telegram_down
    service: notify.homeassistant
- id: '1559835053688'
  alias: Telegram is up
  - entity_id: sensor.telegram_status
    platform: state
    from: offline
    to: online
    condition: []
  - 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.