Skip to main content

Send messages and files over Telegram from the command-line.

Project description

telegram-send

Version pyversions Downloads License

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

Usage

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.

The --pre flag formats messages as fixed-width text:

telegram-send --pre "monospace"

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"

Telegram-send integrates into your file manager (Thunar, Nautilus and Nemo):

Install

Install telegram-send system-wide with pip:

sudo pip3 install telegram-send

Or if you want to install it for a single user (recommended):

pip3 install telegram-send

If installed for a single user you need to add ~/.local/bin to their path:

echo 'PATH="$HOME/.local/bin:$PATH"' >> ~/.profile

(This will be in effect on the next login, do a . ~/.profile for the impatient.)

And finally configure it with telegram-send --configure if you want to send to your account, telegram-send --configure-group to send to a group or with telegram-send --configure-channel to send to a channel.

Use the --config option to use multiple configurations. For example to set up sending to a channel in a non-default configuration: telegram-send --config channel.conf --configure-channel. Then always specify the config file to use it: telegram-send --config channel.conf "hello".

Examples

Here are some examples to get a taste of what is possible with telegram-send.

Alert on completion of shell commands

Receive an alert when long-running commands finish with the tg alias, based on Ubuntu’s built-in alert. Put the following in your ~/.bashrc:

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 sleep 10.

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.

Periodic messages with cron

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 telegram-send --configure-channel --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 result.

Supervisor process state notifications

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 --telegram option), you can receive notifications whenever one of your processes exits.

Usage from Python

Because telegram-send is written in Python, you can use its functionality directly from other Python programs: import telegram_send. Look at the documentation.

ASCII pictures

Combining --stdin and --pre, we can send ASCII pictures:

ncal -bh | telegram-send --pre --stdin
apt-get moo | telegram-send --pre --stdin

Questions & Answers

How to use a proxy?

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 telegram-send with sudo, you also need to install pysocks with sudo.

Uninstall

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

telegram-send-0.10.tar.gz (9.0 kB view details)

Uploaded Source

Built Distribution

telegram_send-0.10-py2.py3-none-any.whl (13.5 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file telegram-send-0.10.tar.gz.

File metadata

File hashes

Hashes for telegram-send-0.10.tar.gz
Algorithm Hash digest
SHA256 d1432cc97530eaf55e7a8cb59145ac55fb46bade320348d1631f011e4f3dee62
MD5 2f2ff62c1d49eb1457cbdc85a9642f63
BLAKE2b-256 1fbf218a4ad3637451555f783e58b3ddc33d741668ac96a6b91c4e5fc2d701e1

See more details on using hashes here.

File details

Details for the file telegram_send-0.10-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for telegram_send-0.10-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 cfdc9130ccf9921396fda2a6648dfc085ccefa4e33a7c44c26c6192fc5352f2d
MD5 11c1570deaaba71869906a12719b1556
BLAKE2b-256 24e84762ff7fc9f7c4a814c004fa67b2a1c430a2a37c7a82c36e838f0de621de

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page