pingram 0.3.4

Minimal Telegram alerting framework for bots and scripts.

Pingram

Send Telegram messages with one line of Python. No webhooks. No bloat. Just pings.

Pingram is an ultra-lightweight Python wrapper for sending outbound Telegram messages via your bot. It’s designed as a cost-free alternative to email and SMS, focused on one-way “ping”-style messaging — ideal for alerts, reports, logs, and automated notifications.

Looking for a minimal alternative to python-telegram-bot? Pingram avoids the event loop, handlers, and 7.8MB install size, focusing solely on outbound pings with just one method per use case.

---

Lightweight by Design

Pingram prioritizes size, speed, and clarity. Designed to be imported and deployed instantly.

Package	Size
Pingram (core)	~20 KB
Pingram + httpx	~800 KB
python-telegram-bot	~7.8 MB

Result:

• Pingram is over 9× smaller than PTB even with httpx included.
• Pingram core is ~390× smaller than PTB alone.
• That's a ~90% reduction with dependencies, and ~99.7% without.

Perfect for:

• Minimal Docker containers
• Constrained environments
• Clean, single-purpose automation

Features

• Send messages, photos, documents, audio, and video
• Direct method calls: bot.message(), bot.send_photo(), etc.
• Minimalistic architecture (single file, no listeners or webhooks)
• Built on httpx (sync)
• No webhook setup or event loop required

Who is it for?

• Developers who want zero-setup Telegram alerts
• Sysadmins replacing email/SMS for cron/CI jobs
• Raspberry Pi or IoT projects needing compact tooling
• Traders, scrapers, and bots that need lightweight push

Installation

pip install pingram

Quickstart

from pingram import Pingram

bot = Pingram(token="<BOT_TOKEN>")
bot.me()

A simple method for testing your bot's authentication token. Requires no parameters. Returns basic information about the bot in form of a User object. https://core.telegram.org/bots/api#getme

Since every high-level api function returns a http.Response object, you can append the end of a function call using .text to show the raw HTTP response instead of the status code.

bot.message(chat_id=123456789, text="Hello Friend").text

This call returns a success or error message from the Telegram API.

Media Examples

All media-sending methods accept both local file paths and direct URLs.
Ensure URLs are direct links (i.e. ending in .jpg, .mp4, .pdf) and serve correct Content-Type headers.

Send Photo

bot.send_photo(
    chat_id=123456789,
    path="https://example.com/image.jpg",
    caption="Test Photo"
)

From a local file:

bot.send_photo(
    chat_id=123456789,
    path="photo.jpg",
    caption="Local Image"
)

Send Document

bot.send_doc(
    chat_id=123456789,
    path="https://example.com/file.pdf",
    caption="Monthly Report"
)

From a local file:

bot.send_doc(
    chat_id=123456789,
    path="report.pdf",
    caption="Monthly Report"
)

Send Audio

bot.send_audio(
    chat_id=123456789,
    path="https://www.myinstants.com//media/sounds/hello-friend-mr-robot.mp3",
    caption="Greetings."
)

From a local file:

bot.send_audio(
    chat_id=123456789,
    path="audio.mp3",
    caption="Shower Thoughts"
)

Send Video

bot.send_video(
    chat_id=123456789,
    path="https://yourdomain.com/video.mp4",  # must be direct link to .mp4
    caption="Security Footage"
)

From a local file:

bot.send_video(
    chat_id=123456789,
    path="stranger.mp4",
    caption="Security Footage"
)

Additional Request Data

Including additional data such as a caption, description or any other key, value types supported by the Telegram API can be passed through any API call simply by including it in the params of the function.

bot.send_video(
    chat_id=123456789,
    path="hamsters.mp4",
    caption="Playful Hamsters",
    has_spoiler=True
)

The has_spoiler parameter is a native Telegram option. It must be passed as a bool.

Benefits

• Zero dependencies (core only) — optional httpx for HTTP transport
• Drop-in compatible with shell scripts, cron jobs, CI pipelines, and Python daemons
• Portable single-file design — easy to vendor or embed in other tools
• No auth handshakes or token refreshes — Telegram bots use static tokens
• Reliable delivery with near-instant notifications across devices
• Bypasses email blacklists and spam filters
• Built for automation — ideal for alerts, monitoring, backups, and trading systems
• Rich media support — send screenshots, logs, documents, audio, and video
• Predictable return values — inspect status_code, .text, or .json() directly
• Excellent replacement for SMTP, SMS, or third-party notification APIs
• Runs anywhere Python runs — from Raspberry Pi to cloud VMs
• No app approval or webhook infrastructure required

Tests

Pingram includes a real-world test suite (no mocks). Tests send actual messages to verify API behavior, which is useful for edge-case detection (e.g., rate limits, content type mismatches).

To run the tests:

# Ensure .env has BOT_TOKEN and CHAT_ID
# .env example:
# BOT_TOKEN=123456789:ABCDEF
# CHAT_ID=123456789
pytest
# To include test failure messages you can use:
pytest -rs

Planned features

• Retry and error handling
• Async mode (httpx.AsyncClient)
• Message templating engine
• Std input/message collectors
• Webhook-to-Telegram bridge
• Package tests and CI integration