[RELEASE] Telegram Bot API (notifications)

Create a virtual device (not app) which can be used for sending notifications using Telegram as the platform. This works well with multiple bots and posting to different chat rooms. Each device is self-contained and bot tokens and/or chat IDs can overlap without issue. For example, I have two set up - one for myself, and one for a family group.

Screenshot of the notifications in action:

Code here:
telegram_notifications_bot.groovy

Telegram Bot Setup Instructions:

To set up, you need to create a Telegram Bot and know its API key / token. You also need to know the chat ID of the chat you want to send messages to. This can be a direct chat (for example just to you) or the chat ID of a group (for announcing to multiple people).

Create a bot by communicating with the @BotFather on Telegram. He'll walk you through the steps.
@BotFather will give you your bot API key in the form of #####:text

For the chat ID, you'll need to message your new bot with your normal Telegram account. Once you have done that, there will be a pending update for your bot. You can fetch that update and get the chat ID from the JSON. This can be done in the browser by calling this URL:

https://api.telegram.org/bot<BOTID>/getUpdates

Parse chat ID from the response JSON:

     {
         "ok":true,
         "result":[{
             "update_id": ####UPDATEID####,
             "message": {
                  "message_id":5,
                  "from":{"id": ####YOURUSERID####,
                  "is_bot":false, 
                  "first_name": ...,
                  "username": ...,,
                  "language_code":"en"
             },
             "chat":{
                  "id": ####CHATID#####,
                  "first_name": ...,
                  "username": ...,
                  "type":"private"
             },
             "date":1575988451,
             "text":"test"}}]
      }

In this example, ####CHATID#### is the value you need for the preferences for the device.

Hubitat Setup Instructions

In the console:

If all went correctly, you should receive a message from the bot in Telegram (Initializing Telegram Hubitat bot). For example, from the built in Notifications app:

This device will then be able to be used for notifications throughout Hubitat.


Low hanging fruit update would be to have the code automatically pull the chat ID of the most recent message using the steps above, but in code. For now, though, it's really easy to grab the chatID manually.

Bi-directional communication (issuing commands to a Telegram bot) is very possible, either through polling (leading to delays), or telegram can notify using webhooks for nearly instant communication. I'm one day into using Hubitat, so I'm not sure yet if there's an easy way to expose a public endpoint for Telegram to call, so webhooks may be more challenging to implement.

9 Likes

your github link says 404.

Thanks - I fixed it. Discourse is changing/breaking the link when it renders the comment - unless I wrap it in link tags. I'm not sure how to get the in-line code preview back, but at least the link seems to work properly now.

I think you could use the make API for bidirectional communication.

Was not that easy to set up, but it works. One app less on my phone!

Glad to hear it worked for you. I'll try to rework the setup process at some point (although my enthusiasm was mainly driven by getting it working initially and I have a lot of other TODOs around Hubitat, so that might be a while out).

Was there anything in particular that you think is work making simpler? I think getting the chat_id is probably the easiest step to automate - there will, unfortunately, always be a step of manually talking to @BotFather.

Thanks for the suggestion. I looked into it, and it almost gets you there. Unfortunately, it doesn't seem to support incoming POST calls, which Telegram requires.

$ curl -X POST -d blah 'http://<ip>/apps/api/129/devices/64/botWebhook?access_token=<token>'; echo
{"error":true,"type":"AppException","message":"Method Not Allowed"}
$

I have figured out that I can support POST incoming calls using a custom app, though, and I have a rough proof of concept for that. Works fine in both local and cloud mode, so Telegram's bot webhooks should be able to access it no problem.

Supporting an app will probably simplify the setup process significantly, too, so I'll probably add that at some point. Being able to interact back to the hub through Telegram could be quite nice - especially as you get into the more complicated Telegram bot setups - you can be quite guided and interactive in the user-experience.

I have always thought having a bot for the house that could send notifications to a user and you could communicate back with would be a great way to interact with the home. I was looking at node-red to do this with hubitat and went as far as setting up the telegram bot with bot father before I got in over my head. If you are going to pursue this and need help testing let me know.

1 Like

I am having trouble getting the chatID, when I got to the provide URL I get {"ok":true,"result":[]} Hoe can I view the JSON?

Edit: I stopped and started the bot and everything worked.

Is there a way to send links in the messages? Maybe a tag or something I am missing in the telegram documentation?

What's the issue you're encountering? I just tried and it works as I'd expect:

Even does link previews if you want (you can turn that off by passing the disable_web_page_preview parameter) using the undocumented |||param=value syntax:

https://hubitat.com/|||disable_web_page_preview=false

As an aside, I did put some effort into the 2-way communication - which requires an app. So, I built app/child apps/child devices and a wizard style setup for setting up Telegram bots and chats (even fetches the chat_id automatically), but I haven't polished it up enough to release yet. I'll try to do so this week or next.

I haven't really figured out the best way to handle commands back to the hub - in terms of configuration and the Bot UI on the Telegram side, so I've kind of put the project on the back burner while I migrate some other stuff over.

I was hoping for something more like a hyperlink in a document. So I could ask a question and include the text yes that then hits a RM endpoint. Or maybe a friendly link to a dashboard.

Yep, try this:

Sure, you can do <a href="http://www.hubitat.com/">links</a> as long as you grok HTML.|||parse_mode=HTML

And to disable the preview and use HTML mode:

Sure, you can do <a href="http://www.hubitat.com/">links</a> as long as you grok HTML.|||parse_mode=HTML&disable_web_page_preview=true

See Telegram Bot API for other parameters you can include after the |||

Weird quark in rule machine, when I paste this:

You have arrived home, would you like to change the mode? <a href="https://cloud.hubitat.com/api/09d7918d-c577-4e9e-bcb2-5362bb825352/apps/2/dashboard/273?access_token=xxxxxx&local=false">Dashboard</a> |||parse_mode=HTML&disable_web_page_preview=true

It is changed to:
You have arrived home, would you like to change the mode? Dashboard |||parse_mode=HTML&disable_web_page_preview=true

I'm guessing that RM is doing something weird with the URL? @bravenel

The original code works fine in the device itself.

Please show more context. Paste it where?

In a rule machine action.

From what I can tell, that is happening in our app ui, not in RM. If you look at the setting it creates, it's already changed it. RM itself is just looking for a string. I'll look into this, as I would agree it's odd.

1 Like

Answer: We discovered long ago that embedded html is a security risk, so we strip it out. No can do.

This is awesome. Thanks! Simple and elegant and does exactly what I wanted.

I can also confirm that this is working great, thank you!

To make the step of getting the Chat ID even more simple, just send /start to @chatid_echo_bot and this bot will directly give you the Chat ID you need

3 Likes

Download the Hubitat app