Skip to main content

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

Project description

.. raw:: html

<h1>

telegram-send

.. raw:: html

</h1>

|License|

Telegram-send is a command-line tool to send messages and files over
Telegram to your account or to a channel. It provides a simple interface
that can be easily called from other programs.

.. raw:: html

<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-generate-toc again -->

**Table of Contents**

- `Usage <#usage>`__
- `Install <#install>`__
- `Examples <#examples>`__

- `alert on completion of shell
commands <#alert-on-completion-of-shell-commands>`__
- `periodic messages with cron <#periodic-messages-with-cron>`__

- `Uninstall <#uninstall>`__

.. raw:: html

<!-- markdown-toc end -->

Usage
=====

To send a message:

.. code:: shell

telegram-send "hello, world"

To send a file:

.. code:: shell

telegram-send --file document.pdf

To send an image with an optional caption:

.. code:: shell

telegram-send --image photo.jpg --caption "The Moon at night"

Install
=======

Install telegram-send system-wide with pip:

.. code:: shell

sudo pip3 install telegram-send

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

.. code:: shell

pip3 install telegram-send

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

.. code:: shell

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

And finally configure it with ``telegram-send --configure`` if you want
to send to your account, 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``:

.. code:: shell

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``.

periodic messages with cron
---------------------------

We can combine telegram-send with
`cron <https://en.wikipedia.org/wiki/Cron>`__ to periodically send
messages. Here we will set up a cron job to send the `Astronomy Picture
of the Day <http://apod.nasa.gov/apod/astropix.html>`__ to the
`astropod <https://telegram.me/astropod>`__ channel.

Create a bot by talking to the
`BotFather <https://telegram.me/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 <https://github.com/rahiel/telegram-send/blob/master/examples/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`` with the content:

.. code:: shell

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 <https://telegram.me/astropod>`__ channel to see the result.

Uninstall
=========

.. code:: shell

sudo pip3 uninstall telegram-send
sudo rm /etc/telegram-send.conf

Or if you installed it for a single user:

.. code:: shell

pip3 uninstall telegram-send
rm ~/.config/telegram-send.conf

.. |License| image:: https://img.shields.io/badge/License-GPLv3+-blue.svg
:target: https://github.com/rahiel/telegram-send/blob/master/LICENSE.txt

Project details


Download files

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

Files for telegram-send, version 0.4.1
Filename, size File type Python version Upload date Hashes
Filename, size telegram_send-0.4.1-py3-none-any.whl (8.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size telegram-send-0.4.1.tar.gz (5.4 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page