Telegram Bot

Introduction

Telegram is similar to Whatsapp: https://telegram.org/ but with full Cross platform support! https://telegram.org/apps and the ability to control Domoticz via Telegram messages. In June 2015 Telegram introduced a bot platform: https://telegram.org/blog/bot-revolution, using this approach there is no need to install any software on your Domoticz system in order to use Telegram purely for notification.

Creating Your Bot and Getting Your Token

Basically follow the instructions on the Telegram website: https://core.telegram.org/bots.

Below is an example of creating a bot called "The Newest One" with a username of "newestbot" and a token of 784324329:EETRNJU3jQEGWQdjNv3llb4bnDSDREGuuuL. It is this token which would allow you to send messages as the bot using http requests, rather than having to register a new Telegram username using a unique phone number.

From your Telegram client - connect to BotFather and follow the conversation below (your inputs are in italics and unindented):

What can this bot do?

BotFather is one bot to rule them all. Use it to create new bot

accounts and manage your existing bots.

About Telegram bots:

https://core.telegram.org/bots

Bot API manual:

https://core.telegram.org/bots/api

Contact @BotSupport if you have questions about the Bot API.

Hello

The call me the Botfather, I can help your create and set up

Telegram bots. Please read this manual before we beging:

http://core.telegram.org/bots

You can control me by sending these commands:

/newbot - create a new bot

/token - generate authorization token

/revoke - revoke bot access token

/setname - change a bot's name

/setdescription - change bot description

/setabouttext - change bot about info

/setuserpic - change bot profile photo

/setcommands - change bot commands list

/setjoingroups - can you bot be added to groups?

/setprivacy - what messages does your bot see in groups?

/deletebot - delete a bot

/cancel - cancel current operation

/newbot

Alright, a new bot. How are we going to call it? Please chose a

name for your bot.

The Newest One

Good. Now let's choose a username for your bot. It must end in

'bot'. Like this, for example: TetrisBot or tetris_bot.

newestbot

Done! Congratulations on your new bot. You will find it at

telegram.me/newestbot. You can now add a description, about

section and profile photo for your bot, see /help for a list of

commands.

Use this token to access the HTTP API:

784324329:EETRNJU3jQEGWQdjNv3llb4bnDSDREGuuuL

For a description of the Bot API, see this page:

https://core.telegram.org/bots/api

Store your bot name, username and token safely.

Test Your New Bot and Get Your chat_id

Have a quick chat with your new bot (Sending '/text' for example (without quotes)), using the username you would want to receive Domoticz notifications on, go to your client and send your bot a message or two, the bot won't respond because you haven't written a program to be the bot. Your chats will be stored on the Telegram server until requested by http request using the token you have just received, they are deleted from the server after a minimum of 24 hours.

Once you have sent some messages to your bot you can now use the http api to retrieve the messages or in this case get the id of your Telegram username. Replace the dummy token with your real token in the url below in any web browser:

https://api.telegram.org/bot784324329:EETRNJU3jQEGWQdjNv3llb4bnDSDREGuuuL/getUpdates

Beware ! the usual error is to forget keyword "bot" after https://api.telegram.org/.

If the JSON shows 'ok', but the result is still empty, try to remove your bot from the chat and add it back. Resend the http command and JSON should show the proper result.

If you have got everything right then JSON like this will be returned:

{"ok":true,"result":[{"update_id":939819607,
"message":{"message_id":81,"from":{"id":1234567,"first_name":"Joe","last_name":"Bloggs","username":"jbloggs"},"chat":
{"id":1234567,"first_name":"Joe","last_name":"Bloggs","username":"jbloggs"},"date":1436104501,"text":"\/devices Study"}},{"update_id":939819608,
"message":{"message_id":82,"from":{"id":1234567,"first_name":"Joe","last_name":"Bloggs","username":"jbloggs"},"chat": 
{"id":1234567,"first_name":"Joe","last_name":"Bloggs","username":"jbloggs"},"date":1436104512,"text":"\/off 1"}}]}

You need the id after "from":{"id": in this case 1234567

This is the id (1234567) of your username you used to send the message to your new bot and the id that you want to recieve notifications from Domoticz.

If the JSON shows 'ok', but the result part is still empty, try to remove your bot from the chat and add it back. Resend the http command and the result JSON should show the expeted data.

Now test your bot can send you a message:

https://api.telegram.org/bot784324329:EETRNJU3jQEGWQdjNv3llb4bnDSDREGuuuL/sendMessage?chat_id=1234567&text=Hello from your bot

Once again if all is right then JSON will be returned:

{"ok":true,"result":{"update_id":939819608,
"message":{"message_id":82,"from":{"id":1234567,"first_name":"Joe","last_name":"Bloggs","username":"jbloggs"},"chat": 
{"id":1234567,"first_name":"Joe","last_name":"Bloggs","username":"jbloggs"},"date":1436104512,"text":"Hello from your bot"}}

And you will recieve a message on your Telegram client.

Setting Domoticz to Use Telegram Bot Nofications

Two methods since Domoticz now has Telegram as a standard notification options. (So you could use both at the same time, eg for a private and a group notification system)

1. In Domoticz under Setup / Settings / Notifications, Telegram - set the Enabled tick box, add the API Key (784324329:EETRNJU3jQEGWQdjNv3llb4bnDSDREGuuuL) and Chat ID (1234567) identified earlier. Press the Test button and then Apply Settings. (if the test does not yield any notification, try to "Apply Settings", come back and try again.)

2. In Domoticz under Setup / Settings / Notifications, Custom HTTP Action - set the Enabled tick box, add the id (1234567) identified earlier to the #TO field and then add the necesary https url to the URL/Action field:

https://api.telegram.org/bot784324329:EETRNJU3jQEGWQdjNv3llb4bnDSDREGuuuL/sendMessage?chat_id=#TO&text=#MESSAGE

Press the Test button and then Apply Settings.

Sending notifications to a channel to inform multiple users

The above sendmessage method works with a single user. If you want more users to receive the notifications, use a channel. First create a channel in Telegram. Don't set it private yet, as you need to obtain the channel id first. Give the channel a @channelName. Add your bot as Administrator (so it can send messages). It will not appear as a connection, so you have to search for it. Send a message to this channel through the bot API:

https://api.telegram.org/bot784324329:EETRNJU3jQEGWQdjNv3llb4bnDSDREGuuuL/sendMessage?chat_id=@channelName&text=123

The response will look like this:

{ "ok" : true, "result" : { "chat" : { "id" : -1001005582487, "title" : "Test Private Channel", "type" : "channel" }, "date" : 1448245538, "message_id" : 7, "text" : "123ds" } }

Now you can convert your channel to private (by deleting channel's link) and set #TO field to "-1001005582487" (use your channel id, without qoutes)

Using Telegram Bot to Send Messages with Curl

You can simple send your https url using Curl:

curl "https://api.telegram.org/bot0000000:KEYKEYKEYKEYKEYKEY/sendMessage?chat_id=12345678&text=test"

However it is better to use this format, what the text is URL encoded and so correclty handled when sent by http:

curl --data chat_id=12345678 --data-urlencode "text=Some complex text $25 78%"  "https://api.telegram.org/bot0000000:KEYKEYKEYKEYKEYKEY/sendMessage"

Using Telegram Bot to Send Photos with Curl

The Telegram Bot api allows you to easily send a photo using the sendPhoto method:

curl -s -X POST "https://api.telegram.org/bot<token>/sendPhoto" -F chat_id=<chatid> -F photo="@/path/to/your/photo.jpg"

The Telegram Bot api has a number of other methods which are well documented be Telegram here https://core.telegram.org/bots/api and also talked about here https://unnikked.ga/getting-started-with-telegram-bots.

Using Telegram Bot to Send Message with Curl from Within Lua

Curl can be directly sent by Lua using the os.execute function:

commandArray = {}
token = "0000000:KEYKEYKEYKEYKEYKEY"
chatid = 12345678
message = 'This is from Lua and another minute has gone by!'
if (devicechanged['Test'] == 'On') then
     os.execute('curl --data chat_id='..chatid..' --data-urlencode "text='..message..'"  "https://api.telegram.org/bot'..token..'/sendMessage" ')
end
return commandArray

Using Telegram Bot to Control Domoticz

This is covered in the wiki page: Remote Control of Domoticz by Telegram Bot