Telegram Owl 🦉

📣 Use it to send deployment notifications, alerts, logs, reports, or media - from scripts, cron jobs, CI/CD pipelines, monitoring tools, or any shell environment.

Whether you're a DevOps engineer automating infrastructure, a developer managing CI/CD pipelines, or just want to notify your Telegram group from a terminal script - Telegram Owl gives you a simple and script-friendly way to do it.

Features

• Send text messages
• Send Rich Markdown and Rich HTML messages
• Attach multiple files
• Silent messages (no notification sound)
• Protect messages (disable forwarding/saving)
• Automatic media type detection (or force as document)
• Send to forum thread topics
• Read input from stdin
• Set environment variables for easy usage
• Configure HTTP or SOCKS5 proxy
• Cross-platform support (Windows, Mac, Linux)
• Fast and lightweight (written in Go)

Installation

npm (macOS, Linux, and Windows)

Install globally:

npm install --global telegram-owl

Or run directly without installing:

npx --yes telegram-owl --token YOUR_BOT_TOKEN --chat YOUR_CHAT_ID --message "Hello from Telegram Owl"

Homebrew (macOS and Linux)

Install with Homebrew

brew tap beeyev/pkg https://github.com/beeyev/pkg
brew install --cask telegram-owl

⚠️ macOS Security Note:

If macOS blocks the app with "cannot be opened because the developer cannot be verified":

# Option 1: Remove quarantine attribute
xattr -d com.apple.quarantine /opt/homebrew/bin/telegram-owl

# Option 2: Allow in System Settings
# Go to: System Settings > Privacy & Security > Allow "telegram-owl"

Scoop Windows

Install with Scoop

scoop bucket add beeyev https://github.com/beeyev/pkg
scoop install telegram-owl

Install with winget

winget install telegram-owl

yay -S telegram-owl-bin

docker run --rm ghcr.io/beeyev/telegram-owl:latest --help

COPY --from=beeyev/telegram-owl:latest /usr/bin/telegram-owl /usr/local/bin/telegram-owl

Binary Releases

For macOS 10.12+, Linux, or Windows, download a binary release here.

🚀 Usage

To start using Telegram Owl, you need to obtain a Telegram bot token and chat ID. You can learn how to get it here.

telegram-owl \
  --token <bot-token> \
  --chat <chat-id or @channel> \
  [--message "your message"] \
  [--attach file1,file2,...] \
  [options]

🔐 Required Flags

⚙️ Common Flags

📌 Examples

Send a Simple Message

telegram-owl -t $BOT_TOKEN -c @mychannel -m "Server status: OK ✅"

Send a Message with Markdown formatting

telegram-owl -t $BOT_TOKEN -c 123456 --format=markdown -m "*Bold text* via Markdown"

Send a Message with HTML formatting

telegram-owl -t $BOT_TOKEN -c 123456 --format=html -m '<b>Bold text</b> via HTML and <a href="http://www.example.com/">inline URL</a>'

Send a Rich Markdown Message

Rich Markdown supports GitHub Flavored Markdown constructs such as headings, tables, task lists, and fenced code blocks. Piping a file preserves its leading and internal whitespace.

telegram-owl -t $BOT_TOKEN -c 123456 --format=rich-markdown --stdin < deployment-report.md

Use rich-html for Telegram Rich HTML:

telegram-owl -t $BOT_TOKEN -c 123456 --format=rich-html -m '<h1>Deployment</h1><p><strong>Passed</strong></p>'

The markdown and html formats use sendMessage and can format attachment captions. The rich-markdown and rich-html formats use sendRichMessage. When attachments are present, Telegram Owl sends them without a caption, then sends the rich message separately. --no-link-preview is not available for rich messages. The attachment upload and rich message are separate requests and are not atomic. If the second request fails, the attachments remain delivered and the error reports that partial delivery.

Send Files with a Message

telegram-owl -t $BOT_TOKEN -c 123456 \
  -m "Daily report attached" \
  -a report.pdf,screenshot.png

Send a Protected, Silent Message

telegram-owl -t $BOT_TOKEN -c 123456 \
  -m "Confidential: Project roadmap" \
  --silent --protect

Pipe Message from File or Command

cat message.txt | telegram-owl -t $BOT_TOKEN -c @devs --stdin

Post in a Forum Thread

telegram-owl -t $BOT_TOKEN -c @forumgroup --thread 67890 -m "New bug report 🐞"

⚙️ Configuration

Set environment variables to simplify usage:

export TELEGRAM_OWL_TOKEN="123:abc"
export TELEGRAM_OWL_CHAT="112451"
export TELEGRAM_OWL_THREAD="67890"
export TELEGRAM_OWL_PROXY="http://proxy.example.com:8080"

Proxy Configuration

telegram-owl can route requests through a proxy. Supply the proxy via --proxy or the TELEGRAM_OWL_PROXY environment variable. Proxy handling is powered by Resty under the hood, so any scheme supported by Resty (http, https, socks5) works here.

• HTTP(S) proxy:

telegram-owl --proxy http://proxy.local:3128 -t $BOT_TOKEN -c @channel -m "Hello via proxy"

• SOCKS5 proxy:

telegram-owl --proxy socks5://127.0.0.1:1080 -t $BOT_TOKEN -c @channel -m "Hello via SOCKS5"

• Authenticated proxy:

telegram-owl --proxy http://user:pass@proxy.local:8080 -t $BOT_TOKEN -c @channel -m "Hello with auth proxy"

Authentication is supported by embedding credentials in the URL, e.g. http://user:pass@proxy.local:3128.

📏 Attachment Limits

🐞 Found a Bug or Want a Feature?

Feel free to open an issue on GitHub.

© License

The MIT License (MIT). Please see License File for more information.

If you like this project, please consider giving me a ⭐