Metadata-Version: 2.1
Name: telegram-send
Version: 0.22
Summary: Send messages and files over Telegram from the command-line.
Home-page: https://github.com/rahiel/telegram-send
Author: Rahiel Kasim
Author-email: rahielkasim@gmail.com
License: GPLv3+
Keywords: telegram send message file
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Utilities
Requires-Python: >=3.5
Requires-Dist: python-telegram-bot (>=12.1.1)
Requires-Dist: colorama
Requires-Dist: appdirs

telegram-send
=============

`Version <https://pypi.org/project/telegram-send/>`__
`pyversions <https://pypi.org/project/telegram-send/>`__
`Downloads <https://www.cpu.re/static/telegram-send/downloads-by-python-version.txt>`__
`License <https://github.com/rahiel/telegram-send/blob/master/LICENSE.txt>`__

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 <#usage>`__
-  `Installation <#installation>`__
-  `Examples <#examples>`__

   -  `Alert on completion of shell
      commands <#alert-on-completion-of-shell-commands>`__
   -  `Periodic messages with cron <#periodic-messages-with-cron>`__
   -  `Supervisor process state
      notifications <#supervisor-process-state-notifications>`__
   -  `Usage from Python <#usage-from-python>`__
   -  `Cron job output <#cron-job-output>`__
   -  `ASCII pictures <#ascii-pictures>`__

-  `Questions & Answers <#questions--answers>`__

   -  `How to use a proxy? <#how-to-use-a-proxy>`__
   -  `How to send the same message to multiple
      users? <#how-to-send-the-same-message-to-multiple-users>`__

-  `Uninstallation <#uninstallation>`__

Usage
=====

To send a message:

.. code:: shell

   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:

.. code:: shell

   telegram-send --format markdown "Only the *bold* use _italics_"
   telegram-send --format html "<pre>fixed-width messages</pre> are <i>also</i> supported"

Note that not all Markdown syntax or all HTML tags are supported. For
more information on supported formatting, see the `formatting
options <https://core.telegram.org/bots/api#formatting-options>`__.

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

.. code:: shell

   telegram-send --pre "monospace"

To send a message without link previews:

.. code:: shell

   telegram-send --disable-web-page-preview "https://github.com/rahiel/telegram-send"

To send a message from stdin:

.. code:: shell

   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) with an optional caption:

.. code:: shell

   telegram-send --file quran.pdf --caption "The Noble Qur'an"

To send an image (maximum file size of 10 MB) with an optional caption:

.. code:: shell

   telegram-send --image moon.jpg --caption "The Moon at Night"

To send a GIF or a soundless MP4 video (encoded as H.264/MPEG-4 AVC with
a maximum file size of 50 MB) with an optional caption:

.. code:: shell

   telegram-send --animation kitty.gif --caption "🐱"

To send an MP4 video (maximum file size of 50 MB) with an optional
caption:

.. code:: shell

   telegram-send --video birds.mp4 --caption "Singing Birds"

To send an audio file with an optional caption:

.. code:: shell

   telegram-send --audio "Pachelbel's Canon.mp3" --caption "Johann Pachelbel - Canon in D"

To send a location via latitude and longitude:

.. code:: shell

   telegram-send --location 35.5398033 -79.7488965

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

|image0|

Installation
============

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 without root permissions:

.. code:: shell

   pip3 install telegram-send

If installed for a single user you need to add ``~/.local/bin`` to their
path, refer to this
`guide <https://www.rahielkasim.com/installing-programs-from-non-system-package-managers-without-sudo/>`__
for instructions.

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

The ``-g`` option uses the global configuration at
``/etc/telegram-send.conf``. 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.)

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``. 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 <https://github.com/dschep/ntfy>`__ with the Telegram backend.

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`` (as root) 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.

Supervisor process state notifications
--------------------------------------

`Supervisor <http://supervisord.org>`__ controls and monitors processes.
It can start processes at boot, restart them if they fail and also
report on their status.
`Supervisor-alert <https://github.com/rahiel/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 <https://www.rahielkasim.com/telegram-send/docs/api/>`__.

Cron job output
---------------

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:

.. 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 * * * * 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 <https://joeyh.name/code/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 (``2>&1``).

Here we’ve installed telegram-send system-wide with ``sudo`` and use the
global configuration (``-g``) so ``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 ``.`` either.

ASCII pictures
--------------

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

.. code:: shell

   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:

.. code:: shell

   https_proxy=https://ip:port telegram-send "hello"

Within Python you can set the environment variable with:

.. code:: python

   os.environ["https_proxy"] = "https://ip:port"

If you have a SOCKS proxy, you need to install support for it:

.. code:: python

   pip3 install pysocks

If you installed ``telegram-send`` with ``sudo``, you also need to
install ``pysocks`` with ``sudo``.

How to send the same message to multiple users?
-----------------------------------------------

First you configure telegram-send for every recipient you want to send
messages to:

.. code:: shell

   telegram-send --config user1.conf --configure
   telegram-send --config group1.conf --configure-group
   telegram-send --config group2.conf --configure-group
   telegram-send --config channel1.conf --configure-channel

You will need all of the above config files. Now to send a message to
all of the above configured recipients:

.. code:: shell

   telegram-send --config user1.conf \
                 --config group1.conf \
                 --config group2.conf \
                 --config channel1.conf \
                 "Multicasting!"

Uninstallation
==============

.. code:: shell

   sudo telegram-send --clean
   sudo pip3 uninstall telegram-send

Or if you installed it for a single user:

.. code:: shell

   telegram-send --clean
   pip3 uninstall telegram-send

.. |image0| image:: https://cloud.githubusercontent.com/assets/6839756/16735957/51c41cf4-478b-11e6-874a-282f559fb9d3.png



