TG-DropIn: Zero-Dependency Telegram Sidecar

Add Telegram remote control to any Python script — without rewriting anything.

tg-dropin is a zero-dependency Telegram sidecar for long-running scripts, research experiments, training jobs, data pipelines, and automation.

Unlike major bot frameworks that hijack the main loop or require rewriting code around asyncio, tg-dropin acts as a lightweight sidecar that requires no changes to the existing codebase.

Features

• Zero Dependencies: Uses only standard library modules.
• Media Support: Built-in notify, send_image, and send_document utility methods.
• Exception Notifications: Wrap code in a context manager to instantly send tracebacks on crash.
• Security Whitelisting: Only processes messages from explicitly specified CHAT_ID (or list of IDs).

Installation

Install via pip:

pip install tg-dropin

Or just drop it in literally: Copy src/tg_dropin.py directly into the project directory.

Quickstart

from tg_dropin import TelegramSidecar

# Initialize bot with credentials
bot = TelegramSidecar(bot_token="BOT_TOKEN", chat_id=["USER_1_ID", "USER_2_ID"])

# Optional: Register commands with descriptions for the auto-generated /help menu
@bot.command("ping", description="Check if the script is still alive")
def handle_ping(arg):
    return f"pong! Received: ping {arg}" # Handlers that return a string automatically send replies

# Fallback handler for unmatched messages
@bot.set_default_handler
def handle_unknown(text):
    return f"Unknown command: {text}"

# Start the background daemon thread manually
bot.start()

bot.notify("🚀 Script has started!")  # Broadcasts to all authorized chats
bot.send_message("Targeted message", chat_id="USER_1_ID") # Or send to a specific chat

with bot.notify_exceptions(): # Optional: Wrap code to send tracebacks to Telegram in case of an exception
    
    # Main synchronous workload ...

    x = 1/0 # Simulates a crash

bot.send_file("plot.png", caption="Training loss")

# bot.stop() # Optional: stop the bot gracefully (daemon threads exit automatically)

Setup Telegram Bot

1. Open Telegram and message @BotFather.
2. Use /newbot to create a bot and get a token.
3. To get the Chat ID, send a message to the bot, then visit: https://api.telegram.org/bot<BOT_TOKEN>/getUpdates Look for "chat":{"id":123456789} in the response.

Bonus: Bash / CLI Usage

Helper function to send notifications directly from shell scripts:

send_telegram_message() {
    export BOT_TOKEN="bot_token"
    export CHAT_ID="chat_id"
    curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
        -d "chat_id=${CHAT_ID}" \
        --data-urlencode "text=$1" > /dev/null
    
    echo "📣: $1" # prints the message to the terminal
}

# Example usage:
# python train.py && send_telegram_message "Training finished successfully!"