ChatGPT-Telegram-Bot: A Telegram Front End for OpenAI-Compatible APIs

The gap it fills: Telegram as the client, an OpenAI-shaped endpoint as the brain

Most people who want a chat model in Telegram face the same chore: register a bot with BotFather, handle updates, stream partial responses, split long replies, and track per-user history. ChatGPT-Telegram-Bot, branded TeleChat in the README, packages that work. It is aimed at a specific operator: someone who has an API key for an OpenAI-compatible service and wants a working Telegram front end without building one. The README frames the project as a client for "OpenAI-compatible large language model APIs" and explicitly points users elsewhere for Anthropic, Gemini, Vertex AI, Azure, AWS, XAI, Cohere, Groq, Cloudflare and OpenRouter. That routing decision is the whole shape of the project. It is not a multi-provider gateway; it is a single-provider client that expects a compatible endpoint behind it. The README also notes the bot uses the author's own aient SDK rather than the OpenAI SDK, which matters if you were expecting to patch OpenAI client behaviour directly.

How the request path actually runs, from Telegram update to streamed reply

The data flow visible in the README is short. A user message arrives at the bot, which either polls or receives it through WEB_HOOK if that variable is set; the README describes WEB_HOOK as the place where the bot "will listen to it and process the received messages in a timely manner." From there the bot assembles a request against BASE_URL, which defaults to https://api.openai.com/v1/chat/completions, and streams the answer back into the chat with a typewriter-style effect. Rendering goes through the author's md2tgmd project, which handles Markdown conversion for Telegram, and replies longer than Telegram's message limit are split into multiple messages. Message handling is asynchronous and multi-threaded per the feature list, with dialogue isolation between users. Plugins sit in that path as tools: web search through DuckDuckGo by default or Google when GOOGLE_API_KEY and GOOGLE_CSE_ID are both set, URL summarization, ArXiv paper summarization, and a code interpreter. Group chats can run in topic mode, which the README says isolates APIs, dialogue history, plugin configuration and preferences per topic. That is a per-topic state partition, not a shared session.

Model groups and CUSTOM_MODELS: the configuration surface worth reading twice

The model list is the part most likely to trip up a first deployment. MODEL sets the default QA model and defaults to gpt-5, but the README says it can be switched at runtime with the bot's info command, so pinning it in the environment is optional. CUSTOM_MODELS is where the real work happens. It takes a comma-separated list, with a leading hyphen removing a default model and -all clearing every default. Semicolons separate groups and colons name them, so the README's own example reads CUSTOM_MODELS=-all,command,grok-2;GPT:gpt-5,gpt-3.5-turbo;Claude:claude-3-opus,claude-3-sonnet;OTHERS. Models with no explicit group land in OTHERS automatically. Note what that example implies: a model named Claude in this list is still being called through an OpenAI-compatible endpoint, because that is the only request format the bot speaks. The grouping is a UI convenience for picking between endpoints you have already made compatible, not a provider abstraction. If you run many models, this is the variable that determines whether the picker is usable or a flat wall of names.

Getting it running: token, key, base URL, and the access lists

Two variables are marked required in the README's table: BOT_TOKEN, obtained from BotFather, and API_KEY for the OpenAI or third-party service. BASE_URL is only needed for third-party proxies and defaults to the OpenAI endpoint. Access control is a set of comma-separated ID lists: whitelist (default None, meaning open to everyone), BLACK_LIST, ADMIN_LIST, and GROUP_LIST, where any group ID in the list lets all its members use the bot even if they are not whitelisted. Only admins can use /info to configure the bot, per the README. CHAT_MODE selects between global, where all users share configuration, and multiusers, where configurations are independent. NICK controls whether the bot responds to everything or only to messages starting with the bot's name; in a group with no NICK set, the README warns the bot replies to all messages, which is a fast way to annoy a busy channel. Deployment options listed are Docker, fly.io, Koyeb, Zeabur and Replit, with the README describing the last three as one-click. The material does not include the Docker image tag or a compose file, so check the repository for the exact pull command before assuming one.

Where it is the wrong tool: provider lock-in at the request layer

The clearest limitation is structural rather than a bug. The bot speaks one request format. If your Anthropic or Gemini access is a native API rather than an OpenAI-compatible shim, this project will not talk to it, and the README says as much by redirecting those providers to uni-api. That means a two-service deployment for anyone who wants both: uni-api (or one-api, or new-api) in front, this bot behind it. Two services mean two things to upgrade, two sets of logs, and one more network hop where a request can fail. The README's stated reason for the split is reducing maintenance cost, which is a reasonable argument from the maintainer's side but shifts operational surface onto the operator. A second limitation is Telegram itself. Long replies are split, which the README presents as a feature, but split messages arrive as separate events and any downstream tooling that consumes them has to reassemble them. Topic mode isolates state per topic, so a conversation started in one topic does not carry into another; if you expected one continuous thread across a group, that is not what this does.

How it compares with a self-written python-telegram-bot handler

The honest alternative is not another bot project; it is writing the handler yourself with python-telegram-bot, which appears in the repository topics. The difference in approach is where the complexity lives. A hand-written handler gives you direct control over the request object, so you can call Anthropic's native messages API, Gemini's generateContent, or anything else without a translation layer, and you can shape streaming, retries and logging exactly as your deployment needs. What you give up is everything the README lists as features: the model grouping system, the plugin set (DuckDuckGo and Google search, URL and ArXiv summarization, code interpreter), file handling for voice, audio, images and PDF/TXT/MD/python documents, the md2tgmd Markdown rendering, automatic message splitting, follow-up question prediction, inline mode, and the four-language interface. Rebuilding that set is weeks of work, not an afternoon. The trade is between a fixed request format with batteries included and a flexible request format with nothing included. If your provider set is OpenAI-compatible and stable, the fixed format costs you nothing. If it is not, you are writing the handler anyway, and this project becomes a reference rather than a dependency.

Licence, maintenance and what an upgrade actually costs you

The project is GPL-3.0. That is a copyleft licence, and it is worth understanding before you fork. If you distribute a modified version, the GPL's source-availability terms apply to your version; running it as a private bot for your own group is a different situation from shipping a modified binary or image to others. This is not legal advice, and if you plan to redistribute a modified build, get your own read on the obligations. On maintenance: the repository shows a last push in April 2026 and no releases retrieved, so there is no tagged version to pin against. That means upgrades are a matter of tracking the main branch or a Docker image tag, and the README's environment variable table is the contract you are depending on. Variables like CUSTOM_MODELS carry parsing behaviour (hyphen for removal, -all for clearing, semicolon and colon for grouping) that a change could alter without a version number to warn you. Before upgrading, diff the README's variable table against the version you are running and check whether MODEL's default has moved; it is currently gpt-5, and a default that changes under you is a silent behaviour change in any deployment that never set MODEL explicitly.

Editorial conclusion

Adopt it if you already have an OpenAI-compatible endpoint (OpenAI itself, one-api, new-api, or the author's uni-api) and you want a Telegram interface with model groups, file uploads and web search without writing bot code. Do not adopt it if you need native Anthropic, Gemini or Vertex AI protocol support in the bot itself; the README directs those providers to uni-api instead. Before deploying, verify three things in your own environment: that BASE_URL points at a /v1/chat/completions endpoint accepting the OpenAI request shape, that CUSTOM_MODELS parses the way you expect when you use -all, and that the model you set in MODEL actually exists on that endpoint, since the default is gpt-5.

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. yym68686/ChatGPT-Telegram-Bot on GitHub