V-know/ChatGPT-Telegram-Bot: a self-hosted Telegram front end for OpenAI and Azure

What V-know/ChatGPT-Telegram-Bot is for

The project wraps OpenAI's chat and image models in a Telegram bot. The README lists the intended features plainly: streaming replies, DALL-E 3 image generation, 15 preset bot identities, custom identities, a one-tap chat reset, and native Telegram buttons rather than typed slash commands. The audience is someone who wants a Telegram interface to a model they already pay for, and who is willing to run a small server. It is not a hosted service. The homepage points at a running instance, @RoboAceBot, but the repository is the thing you deploy yourself.

The design decision that matters most is user levels. The README describes three per-level settings: RATE_LIMIT, CONTEXT_COUNT and MAX_TOKEN. Each is a mapping where the key is a user level and the value is a number. That means one deployment can serve a free tier and a paying tier from the same process, with different token ceilings and different numbers of messages allowed inside a TIME_SPAN window. If you only ever serve yourself, this is configuration you can ignore. If you hand the bot to a group, it is the part that keeps one person from burning your API budget.

How the bot routes a message to OpenAI or Azure

The repository layout shows the split: ai/, buttons/, chat/, db/, utils/, plus main.py, config.py and chat_modes.yml at the top level. The ai/ directory holds the provider code, and the AI.TYPE key in config.yaml selects between openai and azure, with openai as the documented default. When AI.TYPE is azure, three more keys become relevant: AI.BASE, AI.VERSION and AI.MODEL. The README says AI.BASE comes from the Azure portal's "Keys and Endpoints" section or from Azure OpenAI Studio's code view, AI.VERSION is the Azure OpenAI API version, and AI.MODEL is the deployment name. On the openai path, AI.MODEL is just the model name.

State lives in MySQL. The README's configuration table lists MYSQL as a required parameter, and db/database.sql is the schema you load before first start. Conversation context is therefore server-side, which is what makes the one-click clear function meaningful: clearing a chat is a database operation, not just a client-side reset. requirements.txt pins PyMySQL 1.1.1 and DBUtils 3.0.3 for that layer. Redis 4.5.5 also appears in requirements.txt, though the README's configuration table does not document a Redis key, so what it is used for is not stated.

Streaming is the other architectural choice. The README lists "Real-time (streaming) response" as a feature, and requirements.txt pins openai 1.19.0, the version named in the v2.0.1 release note. Streaming changes the failure mode: a dropped connection mid-reply leaves a partial message rather than an error.

Installing ChatGPT-Telegram-Bot and running a first chat

The README gives a pip path and a Docker path. The pip path assumes Python 3.11 or newer, per the badge at the top of the README. Start by installing the pinned dependencies from the repository root.

pip install -r requirements.txt

Next you need MySQL. The repository ships a compose file for a local instance, and the README gives the command with the file path db/docker-compose.yaml.

docker-compose up -d -f db/docker-compose.yaml

Then load the schema. The README's example substitutes your own username for username.

mysql -uusername -p -e "source db/database.sql"

Configuration lives in config.yaml. The README says to copy the format from config.yaml.example, which is present at the top level of the repository. At minimum you set BOT.TOKEN from @botFather, DEVELOPER_CHAT_ID for error messages, and the MYSQL block. The README suggests @get_id_bot for finding your own Telegram ID. Then start the process.

python main.py | tee >> debug.log

The README's pipe to debug.log is worth keeping, because the same file is where you will look when the bot stops answering. If you would rather not manage Python at all, the published image is the shorter route, and the compose file mounts config.yaml into /app/config.yaml.

docker-compose up -d

Once the process is up, message the bot in Telegram. A streaming reply appears in place rather than arriving as one block, and the button layout is what you use to switch identity or clear the conversation.

Where ChatGPT-Telegram-Bot gets in your way

MySQL is a hard dependency, not an option. The README's configuration table marks MYSQL as required, and there is no documented SQLite fallback or file-backed store. For a single-user bot on a small VPS that is a second service to install, back up and keep patched, and it is the reason the quickest honest deployment is the Docker compose file rather than a bare pip install.

The dependency pins are another constraint. requirements.txt pins python-telegram-bot at 20.3 and openai at 1.19.0. Both are old relative to the release dates in the repository, and the README does not describe an upgrade path or a compatibility matrix. If you already run a newer python-telegram-bot in the same environment, expect a conflict. The Dockerfile avoids the problem by building from python:3.11-slim with its own install, which is a point in favour of the container route.

Several operational questions go unanswered. The README does not document rollback, schema migration between versions, or what happens to stored conversations when the schema changes. The Dockerfile hardcodes the container timezone to Asia/Shanghai, which is a mild surprise if your server sits elsewhere. And the README documents no Redis key even though redis is in requirements.txt, so you cannot tell from the documentation whether Redis is optional or required in practice.

ChatGPT-Telegram-Bot compared with a plain Telegram bot script

The obvious alternative is a short script using python-telegram-bot and the openai client directly, with no database and no config file. The difference is not the model call, which is a few lines either way. It is everything around it. A plain script has no user levels, so RATE_LIMIT, CONTEXT_COUNT and MAX_TOKEN do not exist as concepts. It has no server-side conversation store, so context either lives in memory and dies with the process, or you write the persistence layer yourself. It has no preset identity system, and chat_modes.yml in this repository is what backs the 15 preset identities the README advertises.

Going the other way, if you want a managed bot you do not host, this project is the wrong shape entirely. Nothing in the repository is a hosted offering; the homepage link is a demonstration instance, and the README's deployment section is written for someone with a server. The trade is straightforward: you accept MySQL and a config file in exchange for rate limiting, persistent context and a button interface you did not have to build.

Maintenance, upgrades and the MIT licence

The last push to the default branch was on 2026-09-07, so the repository is not abandoned. The most recent tagged release is v3.0.1 from 2024-12-29, which the release notes describe as "Creating images from text based on DALL·E". Between that release and the last push there is a gap of roughly eight months, which suggests work continues on main without a matching tag. If you deploy from main, you are tracking unreleased code. If you deploy from the published container image tagged latest, you are tracking whatever was last pushed to the registry, which the Makefile builds with docker buildx for linux/amd64 and linux/arm64.

Upgrade cost is dominated by the dependency pins and the database. Bumping openai or python-telegram-bot means testing the ai/ and chat/ paths yourself, since the README documents no upgrade procedure. Any schema change would need a migration you write, because the only database step described is the initial load of db/database.sql.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the whole of the licence implication here; the repository contains no separate terms of service, and nothing in the README addresses what OpenAI's or Azure's own usage terms require of you. Those are separate agreements you hold directly with the provider, and they are not covered by this project's licence.

Editorial conclusion

Adopt it if you want a Telegram interface you control, you already run MySQL, and you are comfortable editing config.yaml before the first start. Do not adopt it if you want a hosted bot you can add with a link and no server, or if you cannot supply an OpenAI or Azure OpenAI key. Before deploying, verify three things: that python-telegram-bot 20.3 installs cleanly against your Python version, that the MySQL schema in db/database.sql loads without errors, and that your Azure deployment name matches the AI.MODEL value if you choose the azure path.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. V-know/ChatGPT-Telegram-Bot on GitHub