Go to file
Fabian Schlenz 7d15d494db Added GPL license. 2020-11-25 18:35:01 +01:00
.gitignore Added a .gitignore. 2017-01-23 19:20:02 +01:00
LICENSE Added GPL license. 2020-11-25 18:35:01 +01:00
README.md Added list of contributors to README. 2020-11-25 18:12:11 +01:00
telegram Added GPL license. 2020-11-25 18:35:01 +01:00
test.sh Added new option `-T` to add a title to the message. 2020-05-07 06:20:29 +02:00

README.md

telegram.sh

What does it do?

Telegram offers the feature of bots. A bot allows automated systems and servers to send telegram messages to users. Quite often it can be useful to send stuff to yourself. A classic application of this would be receiving results of cronjob tasks via email. Or maybe you want to grab a small file from your server, but downloading it via SCP would be too much work or wouldn't work at all because firewall stuff / filters / proxy servers / whatever.

telegram.sh allows you to send such things via telegram.

Examples

# Send a message to yourself, using a bot token and a chat_id.
telegram -t 123456:AbcDefGhi-JklMnoPrw -c 12345 "Hello, World."

# You can define the token and chat_id in environment variables or config files.
# Then you can just use
telegram "Hello, World."

# Split them into multiple lines
telegram "Hello,"$'\n'"World."
# or
echo -e "Hello\nWorld." | telegram -

# Or you send this one message to another chat:
telegram -c 6789 "Hello, Mars."

# You can also send messages to multiple chats:
telegram -c 1234 -c 6789 "Hello, Planets."

# Send stuff via stdin. It will automatically be sent as monospace code:
ls -l | telegram -

# Use markdown in your message (HTML is available as well):
telegram -M "To *boldly* go, where _no man_ has gone before."

# Send a local file.
telegram -f results.txt "Here are the results."

# Or an image, giving you a preview and stuff.
telegram -i solar_system.png # We don't need to send a message if we're
# sending a file.

# Use environment variables to tell curl to use a proxy server:
HTTPS_PROXY="socks5://127.0.0.1:1234" telegram "Hello, World."
# Check the curl documentation for more info about supported proxy
# protocols.

Requirements

Only bash and curl. Listing known chats with -l requires jq, but you can easily use this tool without this.

Installation / configuration

  • Grab the latest telegram file from this repository and put it somewhere.
  • Create a bot at telegram:
    • Search for the user @botfather at telegram and start a chat with him.
    • Use the /newbot command to create a new bot. BotFather will give you a token. Keep this.
  • Use your telegram client to send a message to your new bot. Any message will do.
  • Find your chat id. Run telegram.sh with -l: telegram -t <TOKEN> -l. If you have jq installed, it will nicely list its known chats. The number at the front is your chat id. If you don't have jq installed, it will print a bit of JSON data and tell you what to look for.
  • You now have your token and your chat id. Send yourself a first message: telegram -t <TOKEN> -c <CHAT ID> "Hello there."

Carrying the token and the chat id around can be quite cumbersome. You can define them in 4 different ways:

  1. In a file /etc/telegram.sh.conf.
  2. In a file ~/.telegram.sh.
  3. In environment variables TELEGRAM_TOKEN and TELEGRAM_CHAT.
  4. As seen above as parameters.

Later variants overwrite earlier variants, so you could define token and chat in /etc/telegram.sh.conf and then overwrite the token with your own in ~/.telegram.sh or on the command line.

The files should look like this:

TELEGRAM_TOKEN="123456:AbcDefGhi-JlkMno"
TELEGRAM_CHAT="12345678"

Multiple chat ids can be defined in a config file as a bash array:

TELEGRAM_TOKEN="123456:AbcDefGhi-JlkMno"
CHATS=(12345678, 23456789, 34567)

With such config command telegram.sh "Hello world" will deliver message to all listed chat ids.

Please be aware that you should keep your token a secret.

You can also add permanent proxy settings in there by adding:

export HTTPS_PROXY="socks5://127.0.0.1:1234"

See the curl documentation for more information about which proxy protocols are supported.

Changelog

Version 0.4

  • New option -m to receive the last received message. You could use this e.g. to regularly poll the last message and react on commands. Format of the response is <Message ID> <Sender ID> <Chat ID> <Text>. You could use this feature like this:
    telegram -m | read message_id sender_id chat_id text
    echo "MessageID: $message_id"
    echo "Text:      $text"
    

Contributors

  • abadroot
  • kgizdov
  • rusalex
  • sergiks