Telegram-send is a command-line tool to send messages and files over Telegram to your account, to a group or to a channel. It provides a simple interface that can be easily called from other programs.
Table of Contents
To send a message:
telegram-send "hello, world"
There is a maximum message length of 4096 characters, larger messages will be automatically split up into smaller ones and sent separately.
To send a message using Markdown or HTML formatting:
telegram-send --format markdown "Only the *bold* use _italics_" telegram-send --format html "<pre>fixed-width messages</pre> are <i>also</i> supported"
For more information on supported formatting, see the formatting documentation.
--pre flag formats messages as fixed-width text:
telegram-send --pre "monospace"
To send a message without link previews:
telegram-send --disable-web-page-preview "https://github.com/rahiel/telegram-send"
To send a message from stdin:
printf 'With\nmultiple\nlines' | telegram-send --stdin
With this option you can send the output of any program.
To send a file (maximum file size of 50 MB):
telegram-send --file document.pdf
To send an image with an optional caption (maximum file size of 10 MB):
telegram-send --image photo.jpg --caption "The Moon at night"
To send a location via latitude and longitude:
telegram-send --location 35.5398033 -79.7488965
Telegram-send integrates into your file manager (Thunar, Nautilus and Nemo):
Install telegram-send system-wide with pip:
sudo pip3 install telegram-send
Or if you want to install it for a single user without root permissions:
pip3 install telegram-send
If installed for a single user you need to add
~/.local/bin to their path,
refer to this guide for instructions.
And finally configure it with
telegram-send --configure if you want to send to
telegram-send --configure-group to send to a group or with
telegram-send --configure-channel to send to a channel.
--config option to use multiple configurations. For example to set up
sending to a channel in a non-default configuration:
channel.conf --configure-channel. Then always specify the config file to use
telegram-send --config channel.conf "Bismillah".
-g option uses the global configuration at
Configure it once:
sudo telegram-send -g --configure and all users on the
system can send messages with this config:
telegram-send -g "GNU" (provided
you’ve installed it system-wide.)
Here are some examples to get a taste of what is possible with telegram-send.
Receive an alert when long-running commands finish with the
tg alias, based on
alert. Put the following in your
alias tg='telegram-send "$([ $? = 0 ] && echo "" || echo "error: ") $(history|tail -n1|sed -e '\''s/^\s*[0-9]\+\s*//;s/[;&|]\s*tg$//'\'')"'
And then use it like
sleep 10; tg. This will send you a message with the
completed command, in this case
What if you started a program and forgot to set the alert? Suspend the program
with Ctrl+Z and then enter
fg; telegram-send "your message here".
To automatically receive notifications for long running commands, use ntfy with the Telegram backend.
We can combine telegram-send with cron to periodically send messages. Here we will set up a cron job to send the Astronomy Picture of the Day to the astropod channel.
Create a bot by talking to the BotFather, create a public channel and add
your bot as administrator to the channel. You will need to explicitly search for
your bot’s username when adding it. Then run
--config astropod.conf. We will use the apod.py script that gets the daily
picture and calls telegram-send to post it to the channel.
We create a cron job
/etc/cron.d/astropod (as root) with the content:
SHELL=/bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin # m h dom mon dow user command 0 1 * * * telegram ~/apod.py --config ~/astropod.conf
Make sure the file ends with a newline. Cron will then execute the script every
day at 1:00 as the user
telegram. Join the astropod channel to see the
Supervisor controls and monitors processes. It can start processes at boot,
restart them if they fail and also report on their status. Supervisor-alert
is a simple plugin for Supervisor that sends messages on process state updates
to an arbitrary program. Using it with telegram-send (by using the
option), you can receive notifications whenever one of your processes exits.
Because telegram-send is written in Python, you can use its functionality
directly from other Python programs:
import telegram_send. Look at the
Cron has a built-in feature to send the output of jobs via mail. In this example we’ll send cron output over Telegram. Here is the example cron job:
SHELL=/bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin # m h dom mon dow user command 0 * * * * rahiel chronic ~/script.bash 2>&1 | telegram-send -g --stdin
The command is
chronic ~/script.bash 2>&1 | telegram-send -g --stdin. We run
the cron job with
chronic, a tool from moreutils. Chronic makes sure that
a command produces no output unless it fails. No news is good news! If our
script fails, chronic passes the output through the pipe (
|) to telegram-send.
We also send the output of stderr by redirecting stderr to stdout (
Here we’ve installed telegram-send system-wide with
sudo and use the global
telegram-send is usable in the cron job. Place the
cron job in
/etc/cron.d/ and make sure the file ends with a newline. The
filename can’t contain a
--pre, we can send ASCII pictures:
ncal -bh | telegram-send --pre --stdin apt-get moo | telegram-send --pre --stdin
You can set a proxy with an environment variable:
https_proxy=https://ip:port telegram-send "hello"
Within Python you can set the environment variable with:
os.environ["https_proxy"] = "https://ip:port"
If you have a SOCKS proxy, you need to install support for it:
pip3 install pysocks
If you installed
sudo, you also need to install
sudo telegram-send --clean sudo pip3 uninstall telegram-send
Or if you installed it for a single user:
telegram-send --clean pip3 uninstall telegram-send