Skip to content
rxsklifePublic

About

Free-usage Telegram AI chat bot with in-bot provider and key setup

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

GratisBot

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. /start walks first-time users through a free provider, and /provider adds API keys for any preset or any OpenAI-compatible server. No .env editing is needed for users.
  • Fallback across providers on errors, rate limits, or no output within FIRST_TOKEN_TIMEOUT. Every reply is capped at REPLY_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.
  • /settings shows 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.
  • /benchmark compares 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.

Quickstart

  1. Create a bot: message @BotFather, send /newbot, copy the token.

  2. 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
  3. Send /start to your bot. Put your Telegram user id (from @userinfobot) in ADMIN_USER_IDS.

  4. 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.

Configuration

.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.

Free tags and model info

A model is tagged free based on, in order:

  1. model_meta.<id>.free in providers.yaml.
  2. free: all on 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).
  3. free: keyless: free only while no key is set. Set for OVHcloud, whose anonymous access allows 2 requests per minute per model.
  4. 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).
  5. 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.

Keeping the list current

Model lists are fetched live and stored, per provider, in the configured storage, so serverless deployments share them too:

  • On demand: /model and /settings fetch a provider's list again once it is older than MODEL_CACHE_TTL.
  • Background: polling and --webhook mode also refresh every MODEL_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 :free promos 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

/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 FAIL or T/O. Models not started before BENCHMARK_MAX_SECONDS show SKIP. Missing values show -.
  • Measured tokens/s also feeds the /settings speed stats.

Rate limits and access:

  • Requests run one model at a time per provider (BENCHMARK_CONCURRENCY), paced by benchmark_rpm in providers.yaml: NIM 30, OpenRouter 20, LLM7 10, OVHcloud 2.
  • Each request is limited to BENCHMARK_TIMEOUT seconds.
  • Admins only unless BENCHMARK_ACCESS=all, with a BENCHMARK_COOLDOWN (default 1800 s).
  • BENCHMARK_DAILY=true adds a run of BENCHMARK_DAILY_MAX models after the daily refresh. It is off by default.
  • On Vercel, keep BENCHMARK_MAX_SECONDS under the 300 s function limit.

Hosting

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 /telegram on $PORT and registers $WEBHOOK_URL/telegram with 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 on any VPS

docker compose up -d --build

SQLite is kept in ./data.

Oracle Cloud Always Free

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.

  1. Create an Ubuntu VM (shape VM.Standard.A1.Flex) and SSH in.
  2. Install Docker, then copy this project and .env to the VM.
  3. Run docker compose up -d --build. Polling needs no open ports.

Vercel (Python, webhook)

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.

  1. Create an Upstash Redis database and copy its REST URL and token.
  2. Import the repository in Vercel, or run npx vercel in the project folder.
  3. 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 random WEBHOOK_SECRET. Redeploy.
  4. On your machine, with the same token and WEBHOOK_SECRET in .env, run: python -m bot.main --set-webhook https://<project>.vercel.app/api/webhook
  5. Optional: set CRON_SECRET (16+ random characters). vercel.json defines a daily cron that calls /api/refresh, and Vercel sends the secret as Authorization: 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 after MODEL_CACHE_TTL.

Use the production domain. Preview deployments sit behind Vercel Authentication by default, and Telegram cannot get through it.

Cloudflare Workers

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_IDS and ALLOWED_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 secret keys 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 in wrangler.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 /keep overrides that.
  • /benchmark shows the last results; /benchmark run (admins, cooldown) runs the same 4 checks on BENCHMARK_MAX_MODELS models (default 2) within a 20 s budget. Requests don't stream, so there is no TTFT, and tokens/s is measured over total latency. Set BENCHMARK_CRON_MAX_MODELS to 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=25000 and fast default models.

Deploy:

  1. Install Node 22 or newer. Current Wrangler requires it.
  2. cd worker && npm install
  3. npx wrangler kv namespace create KV, then put the returned id in wrangler.toml.
  4. Set secrets: npx wrangler secret put TELEGRAM_BOT_TOKEN, then the same for WEBHOOK_SECRET, ADMIN_USER_IDS, and each *_API_KEY you use.
  5. npx wrangler deploy
  6. Register the webhook. You can use python -m bot.main --set-webhook https://tg-ai-bot.<subdomain>.workers.dev from the Python project, or call Telegram's setWebhook with secret_token yourself.

Render and Koyeb (webhook)

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.

License

MIT

About

Free-usage Telegram AI chat bot with in-bot provider and key setup

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages