{"id":13611351,"url":"https://github.com/rahiel/telegram-send","last_synced_at":"2025-05-15T07:02:44.060Z","repository":{"id":7956236,"uuid":"56966781","full_name":"rahiel/telegram-send","owner":"rahiel","description":"Send messages and files over Telegram from the command-line.","archived":false,"fork":false,"pushed_at":"2024-03-21T15:09:03.000Z","size":168,"stargazers_count":948,"open_issues_count":29,"forks_count":105,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-04-07T01:11:23.434Z","etag":null,"topics":["command-line","python","telegram"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/telegram-send/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rahiel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-24T10:52:45.000Z","updated_at":"2025-04-05T13:57:23.000Z","dependencies_parsed_at":"2024-01-07T18:08:39.708Z","dependency_job_id":"e3d6e905-302f-4c5f-84de-cafb9e04a665","html_url":"https://github.com/rahiel/telegram-send","commit_stats":{"total_commits":100,"total_committers":11,"mean_commits":9.090909090909092,"dds":"0.31000000000000005","last_synced_commit":"34d7703754d441a6f4c4a7b5b3210759d36078e2"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahiel%2Ftelegram-send","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahiel%2Ftelegram-send/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahiel%2Ftelegram-send/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahiel%2Ftelegram-send/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rahiel","download_url":"https://codeload.github.com/rahiel/telegram-send/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248852112,"owners_count":21171839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line","python","telegram"],"created_at":"2024-08-01T19:01:54.452Z","updated_at":"2025-04-14T08:56:45.239Z","avatar_url":"https://github.com/rahiel.png","language":"Python","readme":"# telegram-send\n\n[![Version](https://img.shields.io/pypi/v/telegram-send.svg)](https://pypi.org/project/telegram-send/)\n[![pyversions](https://img.shields.io/pypi/pyversions/telegram-send.svg)](https://pypi.org/project/telegram-send/)\n[![Downloads](https://img.shields.io/pypi/dm/telegram-send)](https://pypistats.org/packages/telegram-send)\n[![License](https://img.shields.io/badge/License-GPLv3+-blue.svg)](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\u003c!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc --\u003e\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 \u0026 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\u003c!-- markdown-toc end --\u003e\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 \"\u003cpre\u003efixed-width messages\u003c/pre\u003e are \u003ci\u003ealso\u003c/i\u003e 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 \"🐱\"\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![](https://cloud.githubusercontent.com/assets/6839756/16735957/51c41cf4-478b-11e6-874a-282f559fb9d3.png)\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 ] \u0026\u0026 echo \"\" || echo \"error: \") $(history|tail -n1|sed -e '\\''s/^\\s*[0-9]\\+\\s*//;s/[;\u0026|]\\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\u003e\u00261 | telegram-send -g --stdin\n```\n\nThe command is `chronic ~/script.bash 2\u003e\u00261 | 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\u003e\u00261`).\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 \u0026 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","funding_links":[],"categories":["Python","Tools"],"sub_categories":["Bot Libs"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahiel%2Ftelegram-send","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frahiel%2Ftelegram-send","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahiel%2Ftelegram-send/lists"}