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