A free usage Telegram chat bot that works with any OpenAI-compatible API. It ships with presets for NVIDIA NIM, OpenRouter, Mistral, OVHcloud AI Endpoints, LLM7, Groq, Gemini, AIHubMix, Z.AI, Token Harbor, FreeInference, Ollama Cloud, and a custom base URL.
Features:
- Set up from inside Telegram.
/startwalks first-time users through a free provider, and/provideradds API keys for any preset or any OpenAI-compatible server. No.envediting is needed for users. - Fallback across providers on errors, rate limits, or no output within
FIRST_TOKEN_TIMEOUT. Every reply is capped atREPLY_TIMEOUT. - Per-user provider, model, persona, temperature, and memory length, set through
/settings,/provider,/keys,/model,/persona,/reset. - The model picker marks free models with 🆓, lists them first, and defaults to "Free only". Embedding, speech, safety, and other non-chat models are hidden.
/settingsshows the current model's context window, tool support, measured speed, and how old the model list is.- Model lists refresh automatically. If your model stops being free, the bot asks before using it.
/benchmarkcompares the free models on your configured providers and lets you switch to one.- Streaming replies, conversation memory, group support (answers only when mentioned or replied to), admin allowlist (
/allow,/deny), Markdown rendered as Telegram HTML, long replies split. - Polling for local or VPS use, webhook mode for servers and serverless.
-
Create a bot: message @BotFather, send
/newbot, copy the token. -
Configure and run:
cp .env.example .env # set TELEGRAM_BOT_TOKEN python3 -m venv .venv && . .venv/bin/activate pip install -r requirements.txt python -m bot.main
-
Send
/startto your bot. Put your Telegram user id (from @userinfobot) inADMIN_USER_IDS. -
If you want, add a key for everyone on the bot in
.env. Otherwise users can add their own with/provider. OVHcloud AI Endpoints and LLM7 work without a key, at low rate limits, so the bot is usable right after step 3.
Adding a key in the bot: /provider → pick a provider → tap "Paste my key" → send the key. The bot deletes the message containing the key after saving it. The key page for each provider is one tap away. For another OpenAI-compatible server, pick "Custom" and enter its base URL, model, and optional key.
Tests: pip install -r requirements-dev.txt && pytest. They mock all network calls.
.env holds secrets and defaults:
| Variable | Meaning |
|---|---|
TELEGRAM_BOT_TOKEN |
Token from BotFather |
DEFAULT_PROVIDER |
Provider id from providers.yaml |
<NAME>_API_KEY |
Optional bot-wide key for each provider. A user's own key from /provider takes precedence. Providers with no key and no key_optional are shown with an "add key" prompt instead of being hidden. |
CUSTOM_BASE_URL, CUSTOM_API_KEY, CUSTOM_MODEL |
Any other OpenAI-compatible server |
ADMIN_USER_IDS |
Comma-separated ids. Admins can /allow and /deny users. |
ALLOWED_USER_IDS |
Static allowlist. If it is empty and nobody was allowed with /allow, anyone can use the bot. |
FIRST_TOKEN_TIMEOUT, REPLY_TIMEOUT |
Seconds. Defaults 25 and 120. |
STORAGE_URL |
sqlite:///data/bot.db (default) or upstash |
UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN |
Needed when STORAGE_URL=upstash |
WEBHOOK_URL, WEBHOOK_SECRET, PORT |
Webhook mode |
MODEL_CACHE_TTL |
Seconds a provider's model list is reused before it is fetched again. Default 3600. |
MODEL_REFRESH_INTERVAL |
Seconds between background refreshes in polling and webhook-server mode. Default 86400. |
CRON_SECRET |
Protects /api/refresh on Vercel |
providers.yaml holds providers, the fallback order, and personas:
providers:
myhost:
name: My Host
base_url: https://example.com/v1
api_key_env: MYHOST_API_KEY
key_url: https://example.com/keys
default_model: some-model
key_optional: false
list_models: true
models: [some-model]
free: all
free_note: free tier, rate-limited
model_meta:
some-model: {free: true, context: 131072, tools: true}
fallback_chain: [nim, openrouter, mistral, ovh, llm7]list_models: false is for hosts without /v1/models; models is then the list shown in /model. key_url is the page shown in the in-bot key setup; it is optional.
User-added keys and custom providers are stored in the configured storage (SQLite or Upstash), not in providers.yaml or .env. They are per-user and are never shown in full by /keys. Env keys remain available to every user as a fallback. In a shared deployment, treat the storage as sensitive: it contains those keys in plain text.
A model is tagged free based on, in order:
model_meta.<id>.freeinproviders.yaml.free: allon the provider: every model on that provider's free tier. Set for NVIDIA NIM (free developer access to hosted models), Mistral (free Experiment tier, rate-limited per model), and Groq (free plan).free: keyless: free only while no key is set. Set for OVHcloud, whose anonymous access allows 2 requests per minute per model.- Data from the provider's
/v1/models: ids ending in:free, or zero prompt and completion pricing (OpenRouter);tier: turbo(LLM7, whose anonymous and free-token access only covers turbo models). - Otherwise not tagged. "Free only" hides untagged models, so use "All" for providers without free data.
Context window and tool support come from /v1/models when the provider reports them: OpenRouter (context_length, tools in supported_parameters), Mistral (max_context_length, capabilities.function_calling), LLM7 (context_window, tools_calling), OVHcloud and Groq (context only). NVIDIA NIM reports neither. Missing values show as "unknown" unless you set them in model_meta.
Model lists are fetched live and stored, per provider, in the configured storage, so serverless deployments share them too:
- On demand:
/modeland/settingsfetch a provider's list again once it is older thanMODEL_CACHE_TTL. - Background: polling and
--webhookmode also refresh everyMODEL_REFRESH_INTERVAL. - Manual: admins can force a refresh with
/refresh, which reports newly free models and models that stopped being free or were removed.
What updates automatically:
- OpenRouter
:freepromos and LLM7 tiers come straight from the live data, so new free models appear and ended ones disappear on the next refresh. - For rule-based providers (NIM, Mistral, Groq, OVHcloud, Z.AI), only models in the live list are shown, so delisted models vanish too.
- If a fetch fails, the last good list is kept, and the bot shows its age and the error.
Your selected model:
- If it stops being free or is no longer listed, the bot does not send your next message. It says why and offers a free alternative or "Keep it". Picking a paid model yourself from "All" counts as keeping it.
- Fallback providers whose default model is no longer free switch to one of their free models, or are skipped if they have none.
: completion tokens reported by the provider divided by the time from the first token to the end. It is stored as a rolling average over the last 20 replies and shows "n/a" until measured.
/benchmark shows the last results and how old they are, with a "Run new" button. Results are a ranked table (rank, model, provider, score, TTFT, tokens/s, accuracy), 10 per page, filterable by provider, with "Use N" buttons to switch to a model.
Models tested:
- Free models from the live lists, capped at
BENCHMARK_MAX_MODELS(default 25). - Each provider's default model first, then models that scored well before, then the rest, taken in turns across providers.
Each model gets 4 prompts with checkable answers:
- arithmetic (17 × 23)
- a yes/no syllogism
- exact JSON output
- the output of a one-line Python snippet
Models that report tool support also get a tool-call check (get_weather for Paris). Answers are checked by code, not by another model.
Scoring:
score = 100 × (0.6 × accuracy + 0.2 × speed + 0.2 × reliability)
accuracy = checks passed / checks run
reliability = requests that returned an answer / requests made
speed = mean of ttft_score and tps_score, using whichever was measured
ttft_score = clamp(1 − (median TTFT − 1 s) / 14 s, 0, 1)
tps_score = clamp(mean tokens/s / 100, 0, 1)
How the measurements are taken:
- Tokens/s is the provider-reported completion tokens divided by generation time. For models that think without streaming their reasoning, it is divided by total latency instead, so the hidden thinking time is not left out.
- Models with no successful request score 0 and show
FAILorT/O. Models not started beforeBENCHMARK_MAX_SECONDSshowSKIP. Missing values show-. - Measured tokens/s also feeds the
/settingsspeed stats.
Rate limits and access:
- Requests run one model at a time per provider (
BENCHMARK_CONCURRENCY), paced bybenchmark_rpminproviders.yaml: NIM 30, OpenRouter 20, LLM7 10, OVHcloud 2. - Each request is limited to
BENCHMARK_TIMEOUTseconds. - Admins only unless
BENCHMARK_ACCESS=all, with aBENCHMARK_COOLDOWN(default 1800 s). BENCHMARK_DAILY=trueadds a run ofBENCHMARK_DAILY_MAXmodels after the daily refresh. It is off by default.- On Vercel, keep
BENCHMARK_MAX_SECONDSunder the 300 s function limit.
The bot has two run modes:
python -m bot.main: polling. No public URL needed. Use on your PC, a VPS, or anything always on.python -m bot.main --webhook: serves/telegramon$PORTand registers$WEBHOOK_URL/telegramwith Telegram.
Serverless hosts use api/webhook.py. Run python -m bot.main --set-webhook <url> once to point Telegram at it, and --delete-webhook to go back to polling. Polling and a webhook cannot run at the same time.
Hosts without a persistent disk need STORAGE_URL=upstash. Upstash Redis has a free tier of 500,000 commands per month. The bot uses about 10 to 15 commands per message.
docker compose up -d --buildSQLite is kept in ./data.
Always Free includes Ampere A1 VMs up to 2 OCPUs and 12 GB RAM in total, plus two AMD micro VMs, in your home region. Sign-up asks for a card. Creating an A1 instance can fail with "out of host capacity"; if so, retry later or try another availability domain.
- Create an Ubuntu VM (shape VM.Standard.A1.Flex) and SSH in.
- Install Docker, then copy this project and
.envto the VM. - Run
docker compose up -d --build. Polling needs no open ports.
The Hobby plan is free, for personal and non-commercial use. Python functions run for up to 300 s there, enough for streaming replies. Files in /api become functions; api/webhook.py is the handler, and vercel.json sets maxDuration to 300.
- Create an Upstash Redis database and copy its REST URL and token.
- Import the repository in Vercel, or run
npx vercelin the project folder. - In Project Settings → Environment Variables, set
TELEGRAM_BOT_TOKEN, your API keys,DEFAULT_PROVIDER,ADMIN_USER_IDS,STORAGE_URL=upstash,UPSTASH_REDIS_REST_URL,UPSTASH_REDIS_REST_TOKEN, and a randomWEBHOOK_SECRET. Redeploy. - On your machine, with the same token and
WEBHOOK_SECRETin.env, run:python -m bot.main --set-webhook https://<project>.vercel.app/api/webhook - Optional: set
CRON_SECRET(16+ random characters).vercel.jsondefines a daily cron that calls/api/refresh, and Vercel sends the secret asAuthorization: Bearer <CRON_SECRET>. Hobby allows daily crons only and may run them any time within the scheduled hour. Without the cron, lists still refresh on the first use afterMODEL_CACHE_TTL.
Use the production domain. Preview deployments sit behind Vercel Authentication by default, and Telegram cannot get through it.
The Python bot does not run on Workers as is. Python Workers run on Pyodide and support pure-Python packages, and httpx and openai work there. But python-telegram-bot is not on Cloudflare's list of tested packages, and this project has not been tested on Workers.
The worker/ folder holds a separate, minimal TypeScript Worker instead:
- It chats with fallback across NIM, OpenRouter, Mistral, OVHcloud, LLM7, Groq, and Gemini, keeps memory and settings in Workers KV, answers in groups only when mentioned, and honours
ADMIN_USER_IDSandALLOWED_USER_IDS. - Commands are text only:
/provider [id],/model(lists free models) or/model <id>,/persona [text],/keep,/reset,/refresh(admins),/help. - The Worker uses
wrangler secretkeys only; the in-bot key and custom-provider setup described above is in the Python bot. - Model lists are cached in KV, refreshed on first use after
MODEL_CACHE_TTL_S, and refreshed daily by the cron trigger inwrangler.toml(crons = ["0 4 * * *"]). Remove the[triggers]block if you don't want it. - It warns instead of sending when the selected model is not free or not listed, and
/keepoverrides that. /benchmarkshows the last results;/benchmark run(admins, cooldown) runs the same 4 checks onBENCHMARK_MAX_MODELSmodels (default 2) within a 20 s budget. Requests don't stream, so there is no TTFT, and tokens/s is measured over total latency. SetBENCHMARK_CRON_MAX_MODELSto also run it from the daily cron, which has a 15-minute limit. Keep that at 10 or fewer: each model takes 4 requests, and the free plan allows 50 per invocation.- It has no inline menus, no streaming, and no speed stats.
Limits on the Workers Free plan that matter here:
- 10 ms CPU per request. Waiting on the network does not count.
- 50 outgoing requests per invocation. The Worker does not stream, to stay well under this.
- KV allows 1,000 writes per day on Free, which is roughly 1,000 messages, and it is eventually consistent.
- Cloudflare's limits page says HTTP requests have no duration limit while the client stays connected. A user report (cloudflare-docs#30529) measured a 30 s cap on Free. The Worker therefore uses
REPLY_TIMEOUT_MS=25000and fast default models.
Deploy:
- Install Node 22 or newer. Current Wrangler requires it.
cd worker && npm installnpx wrangler kv namespace create KV, then put the returned id inwrangler.toml.- Set secrets:
npx wrangler secret put TELEGRAM_BOT_TOKEN, then the same forWEBHOOK_SECRET,ADMIN_USER_IDS, and each*_API_KEYyou use. npx wrangler deploy- Register the webhook. You can use
python -m bot.main --set-webhook https://tg-ai-bot.<subdomain>.workers.devfrom the Python project, or call Telegram'ssetWebhookwithsecret_tokenyourself.
Both run the Docker image. Use the command python -m bot.main --webhook and set WEBHOOK_URL to the service's public URL. Neither free tier keeps a disk across restarts, so use STORAGE_URL=upstash.
- Render free web services spin down after 15 minutes without traffic and take about a minute to start again, so the first message after a quiet period is slow. 750 free instance hours per month.
- Koyeb's free instance (one per organization, 512 MB RAM, 0.1 vCPU) scales to zero after an hour without traffic, with a cold start of a few seconds. It cannot use volumes.
MIT