Metadata-Version: 2.0
Name: telegram-send
Version: 0.18.1
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+
Description-Content-Type: UNKNOWN
Keywords: telegram send message file
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
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 :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Utilities
Requires-Dist: python-telegram-bot (>=5.0)
Requires-Dist: colorama
Requires-Dist: appdirs

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 <#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>`__

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

For more information on supported formatting, see the `formatting
documentation <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 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):

.. code:: shell

    telegram-send --file document.pdf

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

.. code:: shell

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

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

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

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.cpu.re/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.cpu.re/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``.

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

.. |Version| image:: https://img.shields.io/pypi/v/telegram-send.svg
   :target: https://pypi.python.org/pypi/telegram-send
.. |pyversions| image:: https://img.shields.io/pypi/pyversions/telegram-send.svg
   :target: https://pypi.python.org/pypi/telegram-send
.. |Downloads| image:: https://www.cpu.re/static/telegram-send/downloads.svg
   :target: https://www.cpu.re/static/telegram-send/downloads-by-python-version.txt
.. |License| image:: https://img.shields.io/badge/License-GPLv3+-blue.svg
   :target: https://github.com/rahiel/telegram-send/blob/master/LICENSE.txt


