Domoticz : How to send Telegram Notifications

Background

Sometimes, it is cool to receive important notifications directly to your phone when something critical is happening. It's even more true when talking about smart home / home automation : basement water flood, some temperature drops, ... really anything you can think off. There is a Telegram integration in Domoticz, but I was not finding what I was looking for in the official documentation. Let's see how it works !

Telegram

Telegram is an instant messaging service similar to WhatsApp or Signal. Most of the software is Open Source. Communications are encrypted and present similarities with the two other previously mentioned messaging services. Of course it works on Android and IOS and there is a desktop version as well.

The Domoticz wiki for that section is located here.

Set up

In the Domoticz UI, under Settings/Notifications, there is a specific area to configure Telegram.

We need 2 parameters : API Key and Chat ID. The API key will allow you to use the Telegram service and the Chat ID will send the message to the right person : you !

Telegram Desktop

All the below actions can be done with the mobile app, but for easiness, I will use the desktop app.

I assume you already have a Telegram account and everything works as it should. Now, start a new chat and search for the following user : BotFather

Once you've found it, send a /start command in the chat.

There is a full list of commands to interact with the bot. What we are looking at is creating a new bot for our own use. 

The username must be unique within the entire Telegram community and must end by bot. I must admit it was challenging to find one : be creative !

I'm not going to reveal my bot name, not sure this is important or not, but my API key is clearly hidden ;) This is the first parameter you will have to fill in Domoticz ! Save it securely.

Next, we need to find the Chat ID. This can be obtained by starting a new conversation to a new bot called get_id_bot. Send it the same command as above : /start and it will respond with your ID : 

This is the second parameter we need to configure in the Domoticz UI :

Now, we can click on the Test button to valide out setup. It should work and you will receive this : 

Ok, this is nicely done, but how can we use this facility in Domoticz now ?

Sending Notifications

Notifications can be applied on any sensor or device inside Domoticz : 

And in a custom event :

The above example (in French) is switching the light behind the TV at sunset for a duration of 300 mins and I'm also sending a message on Telegram stating the light is on. This is a silly example but this is for testing purpose ;)

There are a couple of scenario where notifications are useful : 

• You need to be notified about something serious : flood, abnormal usage for water, gaz, electricity, ...
• You triggered an event reacting to suspicious event : motion detector, ...

Let's configure a notification on a Pi internal temperature sensor, let's say if the temperature is above 40°C you want to receive a message : 

I highlighted the important action in yellow. I have only selected Telegram in the active systems, it means only telegram notifications will be sent for that specific alert.

Of course, you can configure different levels of notification. Let's say if the temp is above 30°C, email notification is enough, if it becomes more critical, maybe a telegram notification is a better idea.

Here is the notification in Telegram : 

By default, if the condition is met, the notification will be sent every 15 mins. You can change that value in the settings page/notifications section.

Sending custom / on-demand Telegram Notifications

There is a way to send custom or on-demand Telegram notifications by sending an API call to Domoticz. This is a very cool feature !

Here is an example : 

https://<domoticz_ip>/json.htm?type=command&param=sendnotification&subsystem=telegram&subject=test&body=Urgent%20Action%20Required!!!

And the result : 

It means, you can send alert outside of any Domoticz context, this is a way to use the feature implemented into Domoticz for other purpose.

Let's say you are mining cryptos on your Pi and you would like to get a Telegram notification when something interesting happens ;)

What about CLI ?

Ok, this is a bit outside of the scope of this article, but who does not like bonus right ?

You can send Telegram messages directly from the command line with a simple bash script using cURL command ! If you have the API key and the Chat ID (we do, we used it earlier), you can actually send this command to the Telegram API endpoint :

# curl 'https://api.telegram.org/bot<YourBOTToken>/sendMessage?chat_id=<channel_id>&text=<text>'

So, based on that, it's very easy to create a simple script replacing the token and chat ID with your own values.

#!/bin/bash

    

GROUP_ID=<group_id>

BOT_TOKEN=<bot_token>

# this 3 checks (if) are not necessary but should be convenient

if [ "$1" == "-h" ]; then

  echo "Usage: `basename $0` \"text message\""

  exit 0

fi

if [ -z "$1" ]

  then

    echo "Add message text as second arguments"

    exit 0

fi

if [ "$#" -ne 1 ]; then

    echo "You can pass only one argument. For string with spaces put it on quotes"

    exit 0

fi

curl -s --data "text=$1" --data "chat_id=$GROUP_ID" 'https://api.telegram.org/bot'$BOT_TOKEN'/sendMessage' > /dev/null

This is quick and dirty but amazingly efficient !

# ./sendTelegram.sh "This is a test message"

I would like to thanks to Konstantin Bogomolov for his script and explanations !

I hope this help !