A simple CLI tool to send various types of Telegram messages (text, media, forwards, media groups) to multiple recipients via the Telegram Bot API.
- ✅ Send plain text messages directly from the command line
- ✅ Use a JSON message file to send complex message types (photos, forwards, albums)
- ✅ Support for test mode or bulk recipient list from CSV
- ✅ Saves config (token and test chat ID) between runs
tn [options]| Flag | Description |
|---|---|
--message |
Plain text message to send |
--message-file |
Path to JSON file describing a full message object |
--recipients |
Comma-separated list of Telegram chat IDs |
--recipients-file |
Path to CSV file with a telegram column |
--test |
Send to a cached test chat ID (configured on first use) |
--help |
Show this help message |
Note: You must provide one of
--messageor--message-file, and one of--recipients,--recipients-file, or--test.
tn \
--message "Hello from the CLI!" \
--recipients "123456789,987654321"tn \
--message-file ./examples/photo-message.json \
--recipients-file ./recipients.csvtn \
--message "Test this!" \
--testEach file should be a valid message.json with a type and matching content.
{
"type": "text",
"text": {
"text": "Hello, this is a plain text message."
}
}{
"type": "photo",
"photo": {
"url": "https://example.com/image.jpg",
"caption": "Here is an image for you!"
}
}{
"type": "forward",
"forward": {
"fromChatID": 123456789,
"messageID": 42
}
}💡 This forwards a message (by ID) from another chat.
{
"type": "media_group",
"media_group": {
"urls": [
"https://example.com/photo1.jpg",
"https://example.com/photo2.jpg",
"https://example.com/photo3.jpg"
],
"caption": "My trip album"
}
}📷 Telegram allows captions only on the first item of a media group.
Your recipients.csv should look like:
name,telegram
Alice,123456789
Bob,987654321
"name","telegram"
Alice,123456789
Bob,987654321
On first use, you’ll be prompted to enter your TELEGRAM_TOKEN. It will be cached locally for future runs, along with the test chat ID.
make build