father-bot/chatgpt_telegram_bot: A Self-Hosted Telegram Front End for OpenAI and Claude

The problem it solves: model access without a browser tab

The README opens with the complaint it is built around: web chatbots are "often laggy, rate-limited, and locked behind a browser tab." The project's answer is to move the client into Telegram and the billing into your own provider account. You supply an OpenAI API key, optionally an OpenRouter key, and a Telegram bot token from @BotFather. The bot process then talks to the providers directly, so the request ceiling is whatever your provider account allows rather than a quota imposed by an intermediate service.

That framing defines the audience. This is for a single operator or a small trusted group who already have API credit and want a chat interface on a phone without building one. The `allowed_telegram_usernames` setting exists precisely because the natural deployment is private: an empty list leaves the bot open to anyone who finds it, and the README documents the whitelist as the way to restrict access.

The feature set is broad for a project of this shape. Fifteen chat modes ship in `config/chat_modes.yml`, including a Code Assistant, an SQL Assistant and a set of personality prompts. Voice notes are transcribed through Whisper, images are read by any vision-capable model, and image generation runs through OpenAI's `gpt-image-1` in Artist mode. None of that is unusual on its own, but the combination in one deployable unit is the reason someone picks this over writing handlers themselves.

How the bot dispatches across OpenAI and OpenRouter

The repository layout in the README is the clearest description of the architecture. `bot/bot.py` holds the Telegram handlers, streaming logic and commands. `bot/openai_utils.py` does model dispatch, token counting and vision handling. `bot/config.py` loads three YAML files, and `bot/database.py` stores users and dialogs in MongoDB.

The dispatch layer is the interesting part. OpenAI models go through the native API. Claude and GPT-5.5 are routed through OpenRouter, which is why `openrouter_api_key` is a separate config key and why the README says it is "needed only for `provider: openrouter` models." The model catalog lives in `config/models.yml`, and the README states that models can be added or removed there "with no code changes," provided you declare `provider: openrouter` for anything routed that way.

That is a genuine design decision rather than a wrapper. It means the model menu, pricing metadata and capability flags are data, not code, and a new OpenRouter-hosted model should not require touching `openai_utils.py`. The cost is a second credential to manage and a second point of failure in the request path. Token counting is handled with `tiktoken`, which appears in requirements.txt, and the `/balance` command reports spend, though the README does not explain how that figure is derived or whether it reflects provider-side billing or local token accounting.

Installing it and sending a first message

The README gives a two-command path after you have collected credentials. You need an OpenAI API key, optionally an OpenRouter key for Claude and GPT-5.5, and a bot token from @BotFather. The config files ship as examples and must be renamed before the bot will start.

mv config/config.example.yml config/config.yml
mv config/config.example.env config/config.env
# then edit config/config.yml — set telegram_token, openai_api_key (and openrouter_api_key for Claude/GPT-5.5)

After editing `config/config.yml`, start the stack. The compose file defines three services: `mongo`, `chatgpt_telegram_bot` and `mongo_express`. The bot service runs `python3 bot/bot.py` and live-mounts `./config` into `/code/config`, so config edits apply on restart without a rebuild.

docker-compose --env-file config/config.env up --build

The Dockerfile installs `ffmpeg`, which is what voice transcription depends on, and sets `PYTHONUNBUFFERED=1` so logs appear in `docker logs`. Once the container is up, message your bot on Telegram. The README says replies usually take three to five seconds and that streaming can be enabled with `enable_message_streaming`, which prints answers word-by-word. Useful first commands are `/new` to start a dialog, `/mode` to pick one of the fifteen chat modes, and `/settings` to choose a model.

The MongoDB dependency is heavier than it looks

This is the part worth pausing on before you deploy. The compose file runs `mongo:latest` with a bind mount at `./mongodb` and a comment that reads `# TODO: add auth`. There is no authentication configured on the database. The port is bound to `127.0.0.1`, which limits exposure to the host, but any process on that host can read the dialog store.

The same file runs `mongo-express` on port 8081, also bound to localhost, with basic auth credentials defaulting to `username` and `password` through environment variables. Those defaults are documented in the compose file itself, so they are not hidden, but they are also not changed for you. If you deploy this on a shared machine or a VPS with other tenants, both the database and the admin UI are reachable by anyone with local access.

The second cost is operational. A Telegram bot that stores dialogs in MongoDB needs a database running before the bot starts, which is why `depends_on` is present. For a hobby deployment that is fine. For anyone expecting a single binary or a SQLite file, this is a heavier footprint than the feature list implies, and the README does not describe a backup or migration path for the stored dialogs.

What it does not do, and when to pick something else

The README is silent on several things a production operator would ask about. There is no documented rollback procedure, no migration guide for the MongoDB schema, and no explanation of how `/balance` computes spend. The changelog mentions a migration to the OpenAI Python 1.x SDK and a move to Python 3.12, but the README does not describe what happens to existing dialog data across such upgrades.

A more direct comparison is with running your own handlers on top of `python-telegram-bot` directly, which is the library this project uses at version 20.8. That approach gives you control over storage, access control and model routing without inheriting a MongoDB dependency or a config schema you did not design. The trade is time: you would rebuild streaming, vision, voice transcription, the mode system and the settings menu yourself. This project is worth it when those features matter and you want them today; it is the wrong choice when your requirement is a minimal, stateless relay between Telegram and one model.

There is also the question of who the bot is for. The README points at a hosted instance, @jadvebot, and a web front end at jadve.com. If your goal is simply to use a ChatGPT bot in Telegram rather than to run one, the hosted option exists and the self-hosting path is optional.

Maintenance, licensing and upgrade cost

The repository is not archived and the last push was on 2026-06-14, which is recent enough that the project is being worked on. Release v1.6, dated the same day, added OpenRouter support along with Claude and GPT-5.5. The gap before that is notable: v1.5 landed in April 2024 and v1.4 in April 2023, so the project has had long quiet stretches punctuated by substantial feature releases. Plan for that rhythm rather than assuming continuous small updates.

The licence is MIT. In practical terms that permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. It does not grant trademark rights, and it comes with no warranty. This is a description of the licence text, not legal advice; if you intend to redistribute a modified version or run it as part of a commercial service, have someone qualified review the notice requirements.

Upgrade cost is mostly configuration drift. Because models are declared in `config/models.yml` and prompts in `config/chat_modes.yml`, a pull that changes those files can conflict with local edits. The compose file live-mounts `./config`, so a restart picks up changes immediately, which cuts both ways: an accidental edit takes effect without a rebuild. The `requirements.txt` pins `python-telegram-bot[rate-limiter]==20.8` and `pymongo==4.6.3` exactly while allowing `openai>=1.40.0,<2.0.0`, so a rebuild can pull a newer OpenAI SDK within that range without warning.

Editorial conclusion

Adopt it if you want a Telegram client for models you already pay for, you are comfortable running Docker Compose plus MongoDB, and you accept that your dialogs sit in an unauthenticated database on localhost. Do not adopt it if you need a managed service, multi-tenant isolation, or anything beyond a single trusted operator. Before deploying, verify three things: that `allowed_telegram_usernames` is populated rather than left empty, that the Mongo port is bound to 127.0.0.1 as docker-compose.yml shows, and that `config/config.yml` points at the model names your provider account can actually call.

Frequently asked questions

Official sources

1. father-bot/chatgpt_telegram_bot on GitHub
2. License: MIT
3. Project website
4. README
5. Releases