bot-runner

Telegram bot that bridges messages to an AI agent backend. Supports a custom REST API or any OpenAI-compatible endpoint (via LiteLLM). Maintains per-user conversation history in memory.

Setup

Requires Python 3.13+ and uv.

uv sync
cp .env.example .env
# Edit .env with your settings

Usage

# Polling mode (local development)
uv run python main.py

# Webhook mode (production, behind a reverse proxy)
MODE=webhook uv run python main.py

Configuration

All configuration is via environment variables or .env file.

Variable	Required	Default	Description
TELEGRAM_BOT_TOKEN	yes	--	Bot token from @BotFather
ALLOWED_USERS	no	""	Comma-separated Telegram usernames (empty = allow all)
AGENT_TYPE	no	rest	rest or litellm
AGENT_API_URL	when rest	--	Agent REST API endpoint
AGENT_API_TIMEOUT	no	30	Request timeout in seconds
HISTORY_MAX_MESSAGES	no	50	Max messages kept per user
MODE	no	polling	polling or webhook
WEBHOOK_HOST	when webhook	""	Public HTTPS URL for webhook
WEBHOOK_PORT	no	8443	Port for webhook server
WEBHOOK_PATH	no	/webhook	URL path for webhook endpoint
LITELLM_BASE_URL	when litellm	--	LiteLLM/OpenAI-compatible endpoint URL
LITELLM_API_KEY	when litellm	""	API key for the endpoint
LITELLM_MODEL	when litellm	--	Model name to request
LITELLM_SYSTEM_PROMPT	no	(built-in)	Custom system prompt (overrides the default)

Agent types

rest (default)

Forwards messages to a custom REST API.

Request (POST to AGENT_API_URL):

{"user_id": 123, "message": "hello", "history": [{"role": "user", "content": "hello"}]}

Response:

{"response": "Hi there!"}

litellm

Sends messages to any OpenAI-compatible endpoint via /chat/completions. Includes a built-in system prompt that instructs the model to produce Telegram MarkdownV2 output.

Bot commands

• /start -- greeting message
• /clear -- clear conversation history

Project structure

main.py          -- Entrypoint: polling vs webhook mode
bot.py           -- Telegram handlers and application builder
config.py        -- pydantic-settings config from .env
history.py       -- In-memory per-user conversation history
agent.py         -- Abstract AgentClient + REST implementation
agent_litellm.py -- LiteLLM/OpenAI-compatible implementation