TgUtils

This is a collection of CLI utilities to easily interact with Telegram Bots. The aim is for them to be simple and composable, as in the Unix way.

This software is in very early development, please be gentle :)

Tools

Here is a short overview of the included tools. You can generate man pages at doc/man1 by running make doc. Each tool can also display its own doc, e.g., tgsend -h (quick reference), tgsend -h -v (full manual).

tgsend

tgsend is meant as a quick way to send a message to one or more chats from a Bot account. The list of chats are passed as arguments, and the message is read from standard input. For example,

echo "Hello world!" | tgsend 12121212 34343434

will send the Hello world! message to chats 12121212 and 34343434.

tgrecv

tgrecv works as the dual of tgsend, listening for incoming updates from the Bot and outputting them as JSON in standard output. For example,

tgrecv | jq .[0].message

after sending Hello bot! from Telegram, will display

{
  "text": "Hello bot!",
  "chat": {
    "last_name": "Ramos",
    "id": 12121212,
    "type": "private",
    "first_name": "Guillermo",
    "username": "gramos"
  },
  "message_id": 315,
  "from": {
    "last_name": "Ramos",
    "id": 12121212,
    "language_code": "en",
    "username": "gramos",
    "is_bot": false,
    "first_name": "Guillermo"
  },
  "date": 1561469046
}

One important thing to consider is that Telegram by default does not discard any update until it is confirmed to be read by using the offset parameter on the next call. That means that the previous example will keep receiving the same update over and over. tgrecv offers two ways of dealing with this:

• When using the --auto-offset argument it will automatically discard every processed update by caching the last known offset. This is probably the desired behaviour if there are no more consumers connected to the Bot.
• When using the --offset <offset> argument it will discard the updates previous to the given offset.

tgserver

tgserver listens for Telegram updates from the Bot, and for every update, it runs a given program with its standard input piped to the update and having its standard output sent back as response. This program is heavily inspired by tcpserver (from D. J. Bernstein's ucspi-tcp).

For example:

tgserver -- sort

will respond to each message with the same input with the lines sorted alphabetically.

Authentication

To get the Bot token, each program will check (in order):

• The --token CLI argument
• The TGUTILS_TOKEN environment variable
• The contents of $XDG_CONFIG_HOME/tgutils_token (usually ~/.config/tgutils_token)