telegram.bot <img src="resources/telegram.bot.logo.png" alt="telegram.bot" title="telegram.bot" align="right" style="filter: brightness(var(--value, 200%)" data-type="%" height="180"/>

telegram.bot is a bash script to send Telegram messages on Debian-based distributions.

Goal is to have the installation foot print as low as possible, but it still dependes on curl and jq.

This script is based on https://github.com/NicolasBernaerts/debian-scripts/tree/master/telegram

Usage
Install/Update
Uninstall
Commands

Usage

For using telegram.bot, you need a Telegram account and app. See telegram.org on how to set this up. Once you have Telegram installed, you need to create a bot and get an API token for it. This can be done by talking to @BotFather in your Telegram app. Follow this guide, or google for it.

The API token is a string like 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw that is required to authorize your requests for communication via the Telegram Bot API. Once you have obtained an API token to authorize your bot, you can start using telegram.bot.

First thing you should do is to test if your API token is valid. The test will finish silently, if the API token is valid, and it will return the Telegram server's reply, if the API token is invalid, e.g.

beep@projects:~$ telegram.bot --test_token --bottoken 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw
{"ok":false,"error_code":404,"description":"Not Found"}
beep@projects:~$

Once you have an API token for your bot, you need a chat id to which the bot should talk to. The chat id is not easy to find, but telegram.bot will help you.

You have two options:

You either make the bot to chat with you directly, then you need your personal chat id.
Or you make the bot to chat with a group, then you have to add the bot to that group.

<sub>(One note about bots in groups: By default, bots can only read commands which are posted in groups and not all messages. A command is a single words ([a-z_0-9]{1,32}) with a prefixed /, e.g. /help. If you want that your bot can receive all messages from a group, you have to promote it to be a group admin. )</sub>

What ever your choice is, send a message to the group or to your bot and call the following command. This will give you a list of chat ids, from which the bot got updates.

beep@projects:~$ telegram.bot --get_chatid --bottoken 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw
[
  {
    "chatid": -1337818101234,
    "name": "condocam.ai"
  },
  {
    "chatid": -575749100,
    "name": "SystaPi"
  },
  {
    "chatid": 8339234211,
    "name": "Beep"
  }
]

With that information, you are ready to go!

beep@projects:~$ telegram.bot --chatid 8339234211 --bottoken 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw --text "Hello World"

Messages are build up by four elements (--document || --photo), --icon, --title and --text which can be used stand alone, or in any combination.

beep@projects:~/git/telegram.bot$ ./telegram.bot --bottoken 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw --chatid 8339234211 --photo resources/telegram.bot.logo.png --success --title "Welcome to telegram\.bot" --text "The *text area*\n_can_ have ~one~ __multiple__ lines\nand Emojis \U1f44d\!\nBut don't forget to escape the reserved characters like \_, \*, \[, \], \(, \), \~, \`, \|\. if you want to use them in your messages\.\nVisit [beep\-projects](https://github.com/beep\-projects/) for more fun projects\."

Install/Update

(Back to Contents)

The script has build in functionality to copy itself to /usr/local/bin, which should be in the path of most Linux distributions. It also resolves its dependencies on curl and jq via apt, which binds it to Debian-based distributions. For updating the script, you can run the same routine as for installation, or just copy the new version of the script on your own to /usr/local/bin.

wget https://github.com/beep-projects/telegram.bot/releases/latest/download/telegram.bot
chmod 755 telegram.bot
sudo ./telegram.bot --install

Uninstall

(Back to Contents)

To uninstall the script, you just have to remove it from /usr/local/bin. You have to decide if you also want to remove curl and jq and remove these packages on your own.

sudo rm /usr/local/bin/telegram.bot
sudo apt purge jq curl

Commands

(Back to Contents)

The script makes use of the official Telegram Bot API. Please check the API for commands that you would like to get added to telegram.bot and start a new discussion for it.

Get Help

(Back to Commands)

Displays the help text on command usage

beep@projects:~$ telegram.bot --help
  telegram.bot: Tool to send a message to a Telegram User or Channel.
  Message is sent from a Telegram Bot and can contain icon, text, image and/or document.
  Main parameters are :
    -h/-?/--help           display this help and exit
    --install              install dependencies, copy telegram.bot to /usr/local/bin and exit (run as root)
    --print_logo           print the telegram.bot logo
    --get_chatid           calls getUpdates on the --bottoken and returns the chat ids found
                           This call will stop after --timeout seconds (or 60 seconds if not specified) if no update is received 
    --get_updates          gets the updates available for --bottoken. Can be restricted to only get updates >= --offset
    --get_update_offset    gets the offset of the last update available for --bottoken
    -test/--test_token     Test if the provided --bottoken is valid
    -del/--delete_commands Delete all commands for the bot identified by --bottoken
    -set/--set_commands "command1=description1" "command2=description2" ... Set the commands for this bot
    -t/--text <text>       Text of the message (use - for piped text)
    -f/--file <file>       File holding the text of the message
    -p/--photo/--picture <file>      Image to display
    -d/--document <file>   Document to transfer
  Options are :
    --title <title>        Title of the message
    --html                 Use HTML mode for text content (markdown by default)
    --disable_preview      Don't create previews for links, image and/or document
    --protected            Protects the contents of the sent message from forwarding and saving
    --silent               Send message in silent mode (no user notification on the client)
    -q/--quiet             Don't print message to stdout
    -v/--verbose           explain what is being done
    --timeout <timeout>    used by --get_chatid  and --get_updates to timeout after <timeout> seconds. 
                           Overwrites the default value 60
    -cid/--chatid <chat-id>    Recipient User or Channel ID
    -bt|-token|--bottoken <bot-token>     Bot Token of your Telegram bot
  Optional icons are :
    --success              Add a success icon
    --warning              Add a warning icon
    --error                Add an error icon
    --question             Add a question mark icon
    --icon <code>          Add

Telegram.bot

Install / Use

README

telegram.bot <img src="resources/telegram.bot.logo.png" alt="telegram.bot" title="telegram.bot" align="right" style="filter: brightness(var(--value, 200%)" data-type="%" height="180"/>

Contents

Usage

Install/Update

Uninstall

Commands

Get Help