» Creating a Telegram bot for personal notifications

Telegram is a relatively new messaging app that touts security and privacy as its main features. It has clients for a huge raft of platforms, and best of all it has a very nice bot API for developers.

I have a personal Telegram bot that I use to send notifications — anything the bot sends to me will pop up in my desktop client, or on my phone. It keeps me informed about automatic deployments, IRC highlights, and more. This is a quick guide on how you can set up your own bot as well.

Step 0: Use Telegram

If you’re not already using Telegram, head on over to https://telegram.org/ and pick a client to use. The sign up process is very straightforward, and shouldn’t take longer than a few minutes.

Once you have one client set up, installing another is even easier as Telegram will send you an authentication code to the original client. Again, the process is very easy to follow and before you know it you can have a Telegram client on every phone, tablet, PC and toaster you own.

Step 1: Create a bot

The BotFather

Creating a bot in Telegram involves talking to another Bot, called The BotFather. Having bot registration handled within the service itself is fairly unique, and thanks to Telegram’s extensive bot support it’s a breeze to use.

You can start a conversation with the BotFather using this link. Once you’ve followed the prompt to start interacting with the bot, send the /newbot command to begin the interactive bot-creation process. As soon as you type /, Telegram will present a list of possible commands which have been provided by the bot, so all you need to do is click on the /newbot option (or just type it out in full and hit enter, if you wish).

The first thing the BotFather asks for is a name for your bot. This is the friendly name displayed when the bot speaks to you. You can enter anything you like here (within reason).

After you’ve picked a name, you need to pick a username. Telegram forces all bots to have a username that ends with ‘bot’. This is how you’ll add the bot to Telegram to begin interacting with it. You might, for example, name your bot “Bob’s Pet Bot” and have a username of BobsPetBot.

Once you’ve picked a name and a username, the BotFather will reply with your bot’s token. That’s it, you’re finished! You can add the bot by searching for the username you picked, or use the convenient link provided by the BotFather.

Step 2: Start a chat and find its ID

To send a message through the Telegram bot API, the bot needs to provide the ID of the chat it wishes to speak in. For a notification bot, you probably want it speaking in a private conversation with just you.

Start a conversation with your bot, and send it any message. This will queue up an updates for the bot containing the details of the message and the chat ID for your conversation. To view recent updates, you call the getUpdates method. This is done by making a HTTP GET request to the URL https://api.telegram.org/bot$TOKEN/getUpdates Where $TOKEN is the token provided by the BotFather in step 1. You can enter this URL straight into your web browser and view the results. You will see something like this (I’ve manually added some line breaks to make it a bit easier to read):

{"ok":true,
 "result":[
   {"update_id":123123123,
    "message":{
      "message_id":12,
      "from":{
        "id":12345,
        "first_name":"Bob",
        "last_name":"Jones",
        "username":"bjones"},
      "chat":{
        "id":12345,
        "first_name":"Bob",
        "last_name":"Jones",
        "username":"bjones",
        "type":"private"},
      "date":1452933785,
      "text":"Hi there, bot!"}}]}

You can see that the update contains a message dictionary, which describes the sender, the chat, the date and the message itself. For private messages the chat and sender are going to be near identical; for group messages they will obviously be different.

What we’re interested in is the chat ID, which is 12345 in the example above. This ID and the bot token is all you need to send a message to yourself.

Step 3: Hello world!

Sending a message is just another HTTP request to the Telegram API. This time instead of calling getUpdates, we need to call sendMessage. The documentation lists two required parameters: chat_id and text. If we want the bot to say “Hello World” to us then the URL would look something like:

https://api.telegram.org/bot$TOKEN/sendMessage?chat_id=12345&text=Hello+World

In this example, $TOKEN is your bot’s token as before, 12345 is the chat ID we found in step 2, and Hello+World is the URL-encoded string we want to send.

If you access this URL in your browser, you should get a Telegram notification from your bot almost immediately. You can probably see at this point how amazingly simple the Telegram API is to use, compared to most other messaging networks or notification frameworks.

Step 4: Sending automated notifications

Because the Telegram API is so simple, it’s really easy to use it from scripts or apps that are performing automated tasks for you. I’ve previously mentioned how I get updates about deployments of this site, but it basically boils down to a very simple cURL call:

#!/bin/bash

CHATID="1234"
KEY="abcd"
TIME="10"
URL="https://api.telegram.org/bot$KEY/sendMessage"
TEXT="Hello world"

curl -s --max-time $TIME -d "chat_id=$CHATID&disable_web_page_preview=1&text=$TEXT" $URL >/dev/null

Substitute in your chat ID and key, and the script should send you another Hello World when you run it. Now whenever something interesting happens in a script or application, you know how to add a one-liner to send yourself a cross-platform notification!

comments powered by Disqus