tgsend - Telegram Messaging Tool

tgsend is a little Python module to send messages, photos and documents to Telegram chats via a Telegram bot. tgsend can be used either as a command line tool or as a module for Python 3.

Quick Start (Command Line)

1. Create a Telegram Bot with the help of @BotFather and take note of the bot token.
2. Start a new chat with your bot or add it to a group where the messages should be sent to. Find out your personal chat ID or the chat ID of the group chat, e.g. by using @Echo_ID_Bot. Important: Telegram Bots are shy, so you have to send the first message in a chat with them.
3. Install tgsend with pip:

sudo pip3 install tgsend

4. Quickly configure tgsend with environment variables (see Configuration for other options). In bash:

TGSEND_TOKEN=abcdefg # your bot token
TGSEND_CHATID=1234567 # the chat ID of the private/ group chat

5. Test it:

tgsend "Hello World"

Usage

From Command Line

Send a text message with formatting:

tgsend --format markdown "This is a text with *bold* and _italic_ words."

Add a title and an icon:

tgsend -t "Title" --icon $'\u2705' "Some text."

Send a picture:

tgsend --photo image.png "Image description."

Send a file:

tgsend --doc log.txt "Log file"

Send a video:

tgsend --video video.mp4 "Video caption"

Send a sticker:

tgsend --sticker sticker.webp

Read from stdin:

cat greeting.txt | tgsend -

Type tgsend --help to see all options.

In Python

Example:

from tgsend import Telegram, ParseMode
# token and chat ID will be searched in config files if not specified here
telegram = Telegram("your-bot-token", "your-chat-id")
# send a text message
telegram.send_message(
    "This is a text with *bold* and _italic_ words.",
    title="The Title",
    parse_mode=ParseMode.MARKDOWN
)

Configuration

A configuration for tgsend always consists of a bot token and a chat ID. These values can be either set through environment variables (as shown above) or through a configuration file.

Per-user and global configuration

You can place a per-user configuration file at ~/tgsend.conf and a global configuration file at /etc/tgsend.conf. If no environment variables are specified, tgsend will look for the required values in these files in the given order. The format of this configuration file should look like this:

[Default]
BotToken = your_bot_token
ChatID = your_chat_id

More configuration options

You can add additional bot token/ chat ID profiles by adding a config section to the configuration file, e.g.:

[AltConfig]
BotToken = different_bot_token
ChatID = another_chat_id

You can then simply switch to this configuration with the -c option:

tgsend -c AltConfig "Hello World"

It is also possible to specify a different location for the configuration file by using the -l option. E.g.:

tgsend -l ~/tgsend/botconfig.conf "Some text"

tgsend will now look for the [Default] section in the given configuration file.

License

This software is pusblished under BSD-3-Clause license.