tg-gateway-bot 0.2.0

Lightweight bidirectional Telegram Bot Gateway — raw HTTP, no heavy SDK, any LLM backend

🤖 tg-gateway

Lightweight bidirectional Telegram Bot Gateway — raw HTTP, no heavy SDK, instant startup.

Turn any OpenAI-compatible LLM into a Telegram bot in seconds.

pip install tg-gateway-bot

Features

• Long-polling — no public IP, no webhook, no ngrok
• Bidirectional — users message the bot → LLM processes → replies stream back
• Streaming — progressively edits messages as the agent generates text
• Access control — whitelist of allowed Telegram user IDs
• Multi-turn history — per-user conversation context (up to 20 messages)
• Message splitting — auto-splits responses > 4096 chars
• Typing indicator — shows "typing..." while processing
• Photo & document support — sends captions to the LLM
• Proxy support — HTTP/SOCKS5
• Graceful shutdown — handles SIGTERM/SIGINT cleanly

Quick Start

1. Install

pip install tg-gateway

2. Create a Telegram Bot

Talk to @BotFather on Telegram and create a new bot. Save the token.

3. Configure

tg-gateway-bot --config config.json

Or create config.json:

{
  "bot_token": "123456:ABCdef...",
  "allow_from": ["your_telegram_user_id"],
  "llm_api_url": "https://api.openai.com/v1/chat/completions",
  "llm_api_key": "sk-...",
  "llm_model": "gpt-4o-mini"
}

How to get your Telegram user ID? Message @userinfobot on Telegram.

4. Run

tg-gateway

Or with a custom config path:

tg-gateway-bot --config /path/to/config.json

5. Message Your Bot

Open Telegram, find your bot, and send it a message! 🎉

Environment Variables

All config fields can be overridden via environment variables:

Variable	Description
TG_BOT_TOKEN	Telegram Bot API token
TG_ALLOW_FROM	Comma-separated allowed user IDs
TG_PROXY	Proxy URL (e.g. socks5://host:port)
TG_STREAMING	Enable/disable streaming (true/false)
TG_USE_MARKDOWN_V2	Use MarkdownV2 formatting
TG_DEBUG	Enable debug logging

Configuration

Field	Default	Description
base_url	https://api.telegram.org	Custom Bot API URL (self-hosted)
streaming	true	Progressive message editing
typing_indicator	true	Show typing while processing
max_message_length	4096	Max chars per message
use_markdown_v2	false	MarkdownV2 parse mode
system_prompt	(see config example)	LLM system prompt
max_history	20	Multi-turn context window

Deployment

For 24/7 operation, run on a VPS or Raspberry Pi:

nohup tg-gateway-bot > gateway.log 2>&1 &

Or use systemd / supervisor / screen / tmux.

Python API

import asyncio
from tg_gateway import TelegramGateway, load_config

async def main():
    cfg = load_config("config.json")
    gateway = TelegramGateway(cfg)
    await gateway.start()

asyncio.run(main())

License

MIT