# telegram-send
[](https://pypi.org/project/telegram-send/)
[](https://pypi.org/project/telegram-send/)
[](https://pypistats.org/packages/telegram-send)
[](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.
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
**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)
<!-- markdown-toc end -->
# Usage
To send a message:
``` 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:
```shell
telegram-send --format markdown "Only the *bold* use _italics_"
telegram-send --format html "<pre>fixed-width messages</pre> are <i>also</i> supported"
telegram-send --format markdown "||Do good and find good!||"
```
Note that not all Markdown syntax or all HTML tags are supported. For more
information on supported formatting, see the [formatting options][]. We use the
MarkdownV2 style for Markdown.
[formatting options]: https://core.telegram.org/bots/api#formatting-options
The `--pre` flag formats messages as fixed-width text:
``` shell
telegram-send --pre "monospace"
```
To send a message without link previews:
``` shell
telegram-send --disable-web-page-preview "https://github.com/rahiel/telegram-send"
```
To send a message from stdin:
``` 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:
``` 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:
``` shell
telegram-send --image moon.jpg --caption "The Moon at Night"
```
To send a sticker:
``` shell
telegram-send --sticker sticker.webp
```
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:
``` shell
telegram-send --animation kitty.gif --caption "🐱"
```
To send an MP4 video (maximum file size of 50 MB) with an optional caption:
``` shell
telegram-send --video birds.mp4 --caption "Singing Birds"
```
To send an audio file with an optional caption:
``` shell
telegram-send --audio "Pachelbel's Canon.mp3" --caption "Johann Pachelbel - Canon in D"
```
To send a location via latitude and longitude:
``` shell
telegram-send --location 35.5398033 -79.7488965
```
All captions can be optionally formatted with Markdown or html:
``` shell
telegram-send --image moon.jpg --caption "The __Moon__ at *Night*" --format markdown
```
Telegram-send integrates into your file manager (Thunar, Nautilus and Nemo):
# Installation
Install telegram-send system-wide with pip:
``` shell
sudo pip3 install telegram-send
```
Or if you want to install it for a single user without root permissions:
``` shell
pip3 install telegram-send
```
If installed for a single user you need to add `~/.local/bin` to their path,
refer to this [guide][] 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.)
[guide]: https://www.rahielkasim.com/installing-programs-from-non-system-package-managers-without-sudo/
# 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`:
``` 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][]
with the Telegram backend.
[ntfy]: https://github.com/dschep/ntfy
## 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][apod] 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
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.
[cron]: https://en.wikipedia.org/wiki/Cron
[apod]: http://apod.nasa.gov/apod/astropix.html
[astropod]: https://telegram.me/astropod
[botfather]: https://telegram.me/botfather
[apod.py]: https://github.com/rahiel/telegram-send/blob/master/examples/apod.py
## 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.
[supervisor]: http://supervisord.org
[supervisor-alert]: https://github.com/rahiel/supervisor-alert
## 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][].
[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:
``` 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][]. 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.
[moreutils]: https://joeyh.name/code/moreutils/
## ASCII pictures
Combining `--stdin` and `--pre`, we can send ASCII pictures:
``` 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:
``` shell
https_proxy=https://ip:port telegram-send "hello"
```
Within Python you can set the environment variable with:
``` python
os.environ["https_proxy"] = "https://ip:port"
```
If you have a SOCKS proxy, you need to install support for it:
``` 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:
``` 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:
``` shell
telegram-send --config user1.conf \
--config group1.conf \
--config group2.conf \
--config channel1.conf \
"Multicasting!"
```
## How to get sticker files?
In Telegram Desktop you right click a sticker and choose "Save Image As...". You
can then send the saved `webp` file with `telegram-send --sticker sticker.webp`.
# Uninstallation
``` shell
sudo telegram-send --clean
sudo pip3 uninstall telegram-send
```
Or if you installed it for a single user:
``` shell
telegram-send --clean
pip3 uninstall telegram-send
```
Raw data
{
"_id": null,
"home_page": "https://github.com/rahiel/telegram-send",
"name": "telegram-send",
"maintainer": "",
"docs_url": "https://pythonhosted.org/telegram-send/",
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "telegram send message file",
"author": "Rahiel Kasim",
"author_email": "rahielkasim@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/79/13/f84085ca81111e54c45105a194844cd79d999801813abdf3674a0cd6086b/telegram-send-0.37.tar.gz",
"platform": null,
"description": "# telegram-send\n\n[](https://pypi.org/project/telegram-send/)\n[](https://pypi.org/project/telegram-send/)\n[](https://pypistats.org/packages/telegram-send)\n[](https://github.com/rahiel/telegram-send/blob/master/LICENSE.txt)\n\nTelegram-send is a command-line tool to send messages and files over Telegram to\nyour account, to a group or to a channel. It provides a simple interface that\ncan be easily called from other programs.\n\n<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->\n**Table of Contents**\n\n- [Usage](#usage)\n- [Installation](#installation)\n- [Examples](#examples)\n - [Alert on completion of shell commands](#alert-on-completion-of-shell-commands)\n - [Periodic messages with cron](#periodic-messages-with-cron)\n - [Supervisor process state notifications](#supervisor-process-state-notifications)\n - [Usage from Python](#usage-from-python)\n - [Cron job output](#cron-job-output)\n - [ASCII pictures](#ascii-pictures)\n- [Questions & Answers](#questions--answers)\n - [How to use a proxy?](#how-to-use-a-proxy)\n - [How to send the same message to multiple users?](#how-to-send-the-same-message-to-multiple-users)\n- [Uninstallation](#uninstallation)\n\n<!-- markdown-toc end -->\n\n# Usage\n\nTo send a message:\n``` shell\ntelegram-send \"Hello, World!\"\n```\nThere is a maximum message length of 4096 characters, larger messages will be\nautomatically split up into smaller ones and sent separately.\n\nTo send a message using Markdown or HTML formatting:\n```shell\ntelegram-send --format markdown \"Only the *bold* use _italics_\"\ntelegram-send --format html \"<pre>fixed-width messages</pre> are <i>also</i> supported\"\ntelegram-send --format markdown \"||Do good and find good!||\"\n```\nNote that not all Markdown syntax or all HTML tags are supported. For more\ninformation on supported formatting, see the [formatting options][]. We use the\nMarkdownV2 style for Markdown.\n\n[formatting options]: https://core.telegram.org/bots/api#formatting-options\n\nThe `--pre` flag formats messages as fixed-width text:\n``` shell\ntelegram-send --pre \"monospace\"\n```\n\nTo send a message without link previews:\n``` shell\ntelegram-send --disable-web-page-preview \"https://github.com/rahiel/telegram-send\"\n```\n\nTo send a message from stdin:\n``` shell\nprintf 'With\\nmultiple\\nlines' | telegram-send --stdin\n```\nWith this option you can send the output of any program.\n\nTo send a file (maximum file size of 50 MB) with an optional caption:\n``` shell\ntelegram-send --file quran.pdf --caption \"The Noble Qur'an\"\n```\n\nTo send an image (maximum file size of 10 MB) with an optional caption:\n``` shell\ntelegram-send --image moon.jpg --caption \"The Moon at Night\"\n```\n\nTo send a sticker:\n``` shell\ntelegram-send --sticker sticker.webp\n```\n\nTo 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:\n``` shell\ntelegram-send --animation kitty.gif --caption \"\ud83d\udc31\"\n```\n\nTo send an MP4 video (maximum file size of 50 MB) with an optional caption:\n``` shell\ntelegram-send --video birds.mp4 --caption \"Singing Birds\"\n```\n\nTo send an audio file with an optional caption:\n``` shell\ntelegram-send --audio \"Pachelbel's Canon.mp3\" --caption \"Johann Pachelbel - Canon in D\"\n```\n\nTo send a location via latitude and longitude:\n``` shell\ntelegram-send --location 35.5398033 -79.7488965\n```\n\nAll captions can be optionally formatted with Markdown or html:\n``` shell\ntelegram-send --image moon.jpg --caption \"The __Moon__ at *Night*\" --format markdown\n```\n\nTelegram-send integrates into your file manager (Thunar, Nautilus and Nemo):\n\n\n\n# Installation\n\nInstall telegram-send system-wide with pip:\n``` shell\nsudo pip3 install telegram-send\n```\n\nOr if you want to install it for a single user without root permissions:\n``` shell\npip3 install telegram-send\n```\n\nIf installed for a single user you need to add `~/.local/bin` to their path,\nrefer to this [guide][] for instructions.\n\nAnd finally configure it with `telegram-send --configure` if you want to send to\nyour account, `telegram-send --configure-group` to send to a group or with\n`telegram-send --configure-channel` to send to a channel.\n\nUse the `--config` option to use multiple configurations. For example to set up\nsending to a channel in a non-default configuration: `telegram-send --config\nchannel.conf --configure-channel`. Then always specify the config file to use\nit: `telegram-send --config channel.conf \"Bismillah\"`.\n\nThe `-g` option uses the global configuration at `/etc/telegram-send.conf`.\nConfigure it once: `sudo telegram-send -g --configure` and all users on the\nsystem can send messages with this config: `telegram-send -g \"GNU\"` (provided\nyou've installed it system-wide.)\n\n[guide]: https://www.rahielkasim.com/installing-programs-from-non-system-package-managers-without-sudo/\n\n# Examples\n\nHere are some examples to get a taste of what is possible with telegram-send.\n\n## Alert on completion of shell commands\n\nReceive an alert when long-running commands finish with the `tg` alias, based on\nUbuntu's built-in `alert`. Put the following in your `~/.bashrc`:\n\n``` shell\nalias tg='telegram-send \"$([ $? = 0 ] && echo \"\" || echo \"error: \") $(history|tail -n1|sed -e '\\''s/^\\s*[0-9]\\+\\s*//;s/[;&|]\\s*tg$//'\\'')\"'\n```\n\nAnd then use it like `sleep 10; tg`. This will send you a message with the\ncompleted command, in this case `sleep 10`.\n\nWhat if you started a program and forgot to set the alert? Suspend the program\nwith Ctrl+Z and then enter `fg; telegram-send \"your message here\"`.\n\nTo automatically receive notifications for long running commands, use [ntfy][]\nwith the Telegram backend.\n\n[ntfy]: https://github.com/dschep/ntfy\n\n## Periodic messages with cron\n\nWe can combine telegram-send with [cron][] to periodically send messages. Here\nwe will set up a cron job to send the [Astronomy Picture of the Day][apod] to\nthe [astropod][] channel.\n\nCreate a bot by talking to the [BotFather][], create a public channel and add\nyour bot as administrator to the channel. You will need to explicitly search for\nyour bot's username when adding it. Then run `telegram-send --configure-channel\n--config astropod.conf`. We will use the [apod.py][] script that gets the daily\npicture and calls telegram-send to post it to the channel.\n\nWe create a cron job `/etc/cron.d/astropod` (as root) with the content:\n\n``` shell\nSHELL=/bin/sh\nPATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin\n\n# m h dom mon dow user command\n0 1 * * * telegram ~/apod.py --config ~/astropod.conf\n```\n\nMake sure the file ends with a newline. Cron will then execute the script every\nday at 1:00 as the user `telegram`. Join the [astropod][] channel to see the\nresult.\n\n[cron]: https://en.wikipedia.org/wiki/Cron\n[apod]: http://apod.nasa.gov/apod/astropix.html\n[astropod]: https://telegram.me/astropod\n[botfather]: https://telegram.me/botfather\n[apod.py]: https://github.com/rahiel/telegram-send/blob/master/examples/apod.py\n\n## Supervisor process state notifications\n\n[Supervisor][] controls and monitors processes. It can start processes at boot,\nrestart them if they fail and also report on their status. [Supervisor-alert][]\nis a simple plugin for Supervisor that sends messages on process state updates\nto an arbitrary program. Using it with telegram-send (by using the `--telegram`\noption), you can receive notifications whenever one of your processes exits.\n\n[supervisor]: http://supervisord.org\n[supervisor-alert]: https://github.com/rahiel/supervisor-alert\n\n## Usage from Python\n\nBecause telegram-send is written in Python, you can use its functionality\ndirectly from other Python programs: `import telegram_send`. Look at the\n[documentation][].\n\n[documentation]: https://www.rahielkasim.com/telegram-send/docs/api/\n\n## Cron job output\n\nCron has a built-in feature to send the output of jobs via mail. In this example\nwe'll send cron output over Telegram. Here is the example cron job:\n\n``` shell\nSHELL=/bin/sh\nPATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin\n\n# m h dom mon dow user command\n0 * * * * rahiel chronic ~/script.bash 2>&1 | telegram-send -g --stdin\n```\n\nThe command is `chronic ~/script.bash 2>&1 | telegram-send -g --stdin`. We run\nthe cron job with `chronic`, a tool from [moreutils][]. Chronic makes sure that\na command produces no output unless it fails. No news is good news! If our\nscript fails, chronic passes the output through the pipe (`|`) to telegram-send.\nWe also send the output of stderr by redirecting stderr to stdout (`2>&1`).\n\nHere we've installed telegram-send system-wide with `sudo` and use the global\nconfiguration (`-g`) so `telegram-send` is usable in the cron job. Place the\ncron job in `/etc/cron.d/` and make sure the file ends with a newline. The\nfilename can't contain a `.` either.\n\n[moreutils]: https://joeyh.name/code/moreutils/\n\n## ASCII pictures\n\nCombining `--stdin` and `--pre`, we can send ASCII pictures:\n\n``` shell\nncal -bh | telegram-send --pre --stdin\napt-get moo | telegram-send --pre --stdin\n```\n\n# Questions & Answers\n\n## How to use a proxy?\n\nYou can set a proxy with an environment variable:\n``` shell\nhttps_proxy=https://ip:port telegram-send \"hello\"\n```\n\nWithin Python you can set the environment variable with:\n``` python\nos.environ[\"https_proxy\"] = \"https://ip:port\"\n```\n\nIf you have a SOCKS proxy, you need to install support for it:\n``` python\npip3 install pysocks\n```\nIf you installed `telegram-send` with `sudo`, you also need to install `pysocks`\nwith `sudo`.\n\n## How to send the same message to multiple users?\n\nFirst you configure telegram-send for every recipient you want to send messages to:\n``` shell\ntelegram-send --config user1.conf --configure\ntelegram-send --config group1.conf --configure-group\ntelegram-send --config group2.conf --configure-group\ntelegram-send --config channel1.conf --configure-channel\n```\n\nYou will need all of the above config files. Now to send a message to all of the\nabove configured recipients:\n``` shell\ntelegram-send --config user1.conf \\\n --config group1.conf \\\n --config group2.conf \\\n --config channel1.conf \\\n \"Multicasting!\"\n```\n\n## How to get sticker files?\n\nIn Telegram Desktop you right click a sticker and choose \"Save Image As...\". You\ncan then send the saved `webp` file with `telegram-send --sticker sticker.webp`.\n\n# Uninstallation\n\n``` shell\nsudo telegram-send --clean\nsudo pip3 uninstall telegram-send\n```\n\nOr if you installed it for a single user:\n``` shell\ntelegram-send --clean\npip3 uninstall telegram-send\n```\n\n\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "Send messages and files over Telegram from the command-line.",
"version": "0.37",
"project_urls": {
"Homepage": "https://github.com/rahiel/telegram-send"
},
"split_keywords": [
"telegram",
"send",
"message",
"file"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c00dae2812bad06bcca55a15284a508dca86242bbbf6fc17907b3787882c96bd",
"md5": "61a6c004e2573e1fcb2569e21b18bec6",
"sha256": "c10dbc83b6bde88a069918f9b98f63eb10742f455ff39736cba77d26bdbdb694"
},
"downloads": -1,
"filename": "telegram_send-0.37-py3-none-any.whl",
"has_sig": false,
"md5_digest": "61a6c004e2573e1fcb2569e21b18bec6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 25815,
"upload_time": "2023-10-07T12:40:18",
"upload_time_iso_8601": "2023-10-07T12:40:18.821018Z",
"url": "https://files.pythonhosted.org/packages/c0/0d/ae2812bad06bcca55a15284a508dca86242bbbf6fc17907b3787882c96bd/telegram_send-0.37-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7913f84085ca81111e54c45105a194844cd79d999801813abdf3674a0cd6086b",
"md5": "330e6f5920fddc6fcf3bd52557d14fbf",
"sha256": "9f69abb331598e4b6ba8a173b15df7dfdec4eec17e3600a43d554c53b0150695"
},
"downloads": -1,
"filename": "telegram-send-0.37.tar.gz",
"has_sig": false,
"md5_digest": "330e6f5920fddc6fcf3bd52557d14fbf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 29265,
"upload_time": "2023-10-07T12:40:21",
"upload_time_iso_8601": "2023-10-07T12:40:21.165280Z",
"url": "https://files.pythonhosted.org/packages/79/13/f84085ca81111e54c45105a194844cd79d999801813abdf3674a0cd6086b/telegram-send-0.37.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-07 12:40:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rahiel",
"github_project": "telegram-send",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "telegram-send"
}
JSON
