Metadata-Version: 2.0
Name: telegram-send
Version: 0.8.7
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 :: 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: appdirs
Requires-Dist: colorama
Requires-Dist: python-telegram-bot (>=2.8.3)

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

|Version| |pyversions| |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.

**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>`__
   -  `supervisor process state
      notifications <#supervisor-process-state-notifications>`__

-  `Uninstall <#uninstall>`__

Usage
=====

To send a message:

.. code:: shell

    telegram-send "hello, world"

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

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: 

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 (recommended):

.. 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"' >> ~/.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, 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``.

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.

Uninstall
=========

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


