Telegram OpenAI-Compatible Bot

Minimal aiogram bot that forwards whitelisted Telegram users' text and voice messages to an OpenAI-compatible API.

Features

Configurable API_BASE_URL and API_TOKEN
Optional proxy for Telegram API and OpenAI-compatible API connections
Telegram typing animation while the model response is streaming
Required users whitelist
Persistent per-user context in SQLite
/new command to reset the current user's context
Per-user message batching before sending to the model
Voice message transcription through a separately configured transcription model
Model-controlled multi-message replies with <break> tags
Configurable model and system prompt
API timeouts, retries, response limits, and safe user-facing fallbacks
System prompt stored in config/system_prompt.txt, not .env

Setup

Install dependencies:

python -m pip install -r requirements.txt

Create local environment config:

cp .env.example .env

Edit .env:

BOT_TOKEN=123456:telegram-token
API_BASE_URL=https://api.openai.com/v1
API_TOKEN=sk-your-api-token
MODEL=gpt-4o-mini
TRANSCRIPTION_MODEL=whisper-1
WHITELIST_USER_IDS=123456789
DATABASE_PATH=data/bot.sqlite3
MAX_CONTEXT_MESSAGES=20
MESSAGE_BATCH_DELAY_SECONDS=3

API_BASE_URL must be the API root. Do not include /chat/completions; the OpenAI SDK appends that path automatically.

TRANSCRIPTION_MODEL is used for Telegram voice message transcription before the transcript is sent to MODEL.

For OpenRouter, use:

API_BASE_URL=https://openrouter.ai/api/v1

Edit config/system_prompt.txt with the system prompt you want.
Run the bot:

python bot.py

Proxy

Set TELEGRAM_PROXY in .env to route both Telegram API and OpenAI-compatible API traffic through a proxy:

TELEGRAM_PROXY=socks5://user:pass@127.0.0.1:1080

Leave it empty when no proxy is needed.

Context

The bot stores successful user/assistant turns in SQLite at DATABASE_PATH. Each Telegram user has separate context, and each new request sends the latest MAX_CONTEXT_MESSAGES stored messages plus the new user message.

Send /new to delete your stored messages and start a fresh conversation.

Voice Messages

Telegram voice notes are downloaded, transcribed with TRANSCRIPTION_MODEL, then the transcript is passed through the same batching and chat-completions flow as text messages.

Telegram does not expose a bot API to mark a voice note as listened in the user interface, so that step is not supported.

Message Batching

MESSAGE_BATCH_DELAY_SECONDS delays the API request after each incoming Telegram message. If the same user sends more messages during that delay, the timer restarts and the messages are sent to the model together as separate entries:

Message 1: first telegram message
Message 2: second telegram message
Message 3: third telegram message

This keeps stacked messages distinct without merging them into one paragraph. Set MESSAGE_BATCH_DELAY_SECONDS=1 for faster replies or a higher value if you often send several short messages in a row.

Multi-Message Replies

The model can split one response into multiple Telegram messages by emitting break tags:

First message
<break>
Second message
<break timeout=5>
Third message after 5 seconds

Supported tags:

<break> sends the next part immediately
<break timeout=5> waits up to 30 seconds before sending the next part

Add this instruction to config/system_prompt.txt if you want the model to use it naturally:

When a reply is better split into multiple Telegram messages, insert <break> between messages. Use <break timeout=5> when the next message should be delayed by 5 seconds.

Security Notes

.env is ignored by git and should contain tokens only.
WHITELIST_USER_IDS is required so the bot cannot accidentally run as a public API proxy.
The bot logs provider errors server-side and sends generic fallbacks to users.
MAX_PROMPT_CHARS and MAX_RESPONSE_CHARS limit oversized requests and Telegram message failures.
data/ is ignored by git because it contains local conversation history.

4.1 KiB Raw Permalink Blame History