English | Chinese

ChatGPT Telegram Bot is a powerful Telegram bot that can use various mainstream large language model APIs, including GPT-3.5/4/4 Turbo/4o/o1, DALL·E 3, Claude2.1/3/3.5 API, Gemini 1.5 Pro/Flash, Vertex AI (Claude series/Gemini series), Groq Mixtral-8x7b/LLaMA2-70b, and DuckDuckGo (gpt-4o-mini, claude-3-haiku, Meta-Llama-3.1-70B, Mixtral-8x7B). It enables users to have efficient conversations and information searches on Telegram.

• Multiple AI Models: Supports GPT-3.5/4/4 Turbo/4o/o1, DALL·E 3, Claude2.1/3/3.5 API, Gemini 1.5 Pro/Flash, Vertex AI (Claude series/Gemini series), Groq Mixtral-8x7b/LLaMA2-70b and DuckDuckGo (gpt-4o-mini, claude-3-haiku, Meta-Llama-3.1-70B, Mixtral-8x7B). Also supports one-api/new-api/uni-api. Utilizes self-developed API to request backend SDK, does not rely on OpenAI SDK.
• Multimodal Question Answering: Supports question answering for voice, audio, images, and PDF/TXT/MD/python documents. Users can directly upload files in the chat box for use.
• Group Chat Topic Mode: Supports enabling topic mode in group chats, isolating APIs, dialogue history, plugin configurations, and preferences between topics.
• Rich plugin system: Supports web search (DuckDuckGo and Google), URL summarization, ArXiv paper summarization, and code interpreter.
• User-friendly interface: Allows flexible switching of models within the chat window and supports streaming output similar to a typewriter effect. Supports precise Markdown message rendering, utilizing another of my projects.
• Efficient Message Processing: Asynchronously processes messages, answers questions in a multi-threaded manner, supports isolated dialogues, and provides unique dialogues for different users.
• Long Text Message Handling: Automatically merges long text messages, breaking through Telegram's single message length limit. When the bot's response exceeds the Telegram limit, it will be split into multiple messages.
• Multi-user Dialogue Isolation: Supports dialogue isolation and configuration isolation, allowing selection between multi-user and single-user modes.
• Question Prediction: Automatically generates follow-up questions, anticipating what users might ask next.
• Multi-language Interface: Supports Simplified Chinese, Traditional Chinese, Russian and English interfaces.
• Whitelist, Blacklist, and Admin Settings: Supports setting up whitelists, blacklists, and administrators.
• Inline Mode: Allows users to @ the bot in any chat window to generate answers without needing to ask questions in the bot's chat window.
• Convenient Deployment: Supports one-click koyeb, Zeabur, Replit deployment with true zero cost and idiot-proof deployment process. It also supports kuma anti-sleep, as well as Docker and fly.io deployment.

The following is a list of environment variables related to the bot's core settings:

The following is a list of environment variables related to robot preferences. Preferences can also be set after the robot is started by using the /info command and clicking the Preferences button:

The following is a list of environment variables related to the bot's plugin settings:

There are two ways to deploy on Koyeb, one is to use the one-click deployment with the Docker image provided by Koyeb, and the other is to import this repository for deployment. Both methods are free. The first method is simple to deploy but cannot update automatically, while the second method is slightly more complex but can update automatically.

Click the button below to automatically deploy using the pre-built Docker image with one click:

⚠️ Note: When deploying with Koyeb, you must add the environment variable WEB_HOOK, otherwise the bot will not be able to receive messages. Use a string like https://appname.koyeb.app as the value for WEB_HOOK, Koyeb will automatically assign a subdomain.

1. Fork this repository Click to fork this repository

2. When deploying, you need to choose the repository method, set Run command to python3 bot.poy, and set Exposed ports to 8080.

3. Install pull to automatically sync this repository.

One-click deployment:

If you need follow-up function updates, the following deployment method is recommended:

• Fork this repository first, then register for Zeabur. Currently, Zeabur does not support free Docker container deployment. If you need to use Zeabur to deploy the bot for this project, you will need to upgrade to the Developer Plan. Fortunately, Zeabur has introduced their sponsorship program, which offers a one-month Developer Plan to all contributors of this project. If you have features you'd like to enhance, feel free to submit pull requests to this project.
• Import from your own Github repository.
• Set the required environment variables, and redeploy.
• If you need function updates in the follow-up, just synchronize this repository in your own repository and redeploy in Zeabur to get the latest functions.

After importing the Github repository, set the running command

pip install -r requirements.txt > /dev/null && python3 bot.py

Select Secrets in the Tools sidebar, add the environment variables required by the bot, where:

• WEB_HOOK: Replit will automatically assign a domain name to you, fill in https://appname.username.repl.co
• Remember to open "Always On"

Click the run button on the top of the screen to run the bot.

Official documentation: https://fly.io/docs/

Use Docker image to deploy fly.io application

flyctl launch --image yym68686/chatgpt:latest

Enter the name of the application when prompted, and select No for initializing Postgresql or Redis.

Follow the prompts to deploy. A secondary domain name will be provided in the official control panel, which can be used to access the service.

Set environment variables

flyctl secrets set BOT_TOKEN=bottoken
flyctl secrets set API=
# optional
flyctl secrets set WEB_HOOK=https://flyio-app-name.fly.dev/
flyctl secrets set NICK=javis

View all environment variables

flyctl secrets list

Remove environment variables

flyctl secrets unset MY_SECRET DATABASE_URL

ssh to fly.io container

flyctl ssh issue --agent
# ssh connection
flyctl ssh establish

Check whether the webhook URL is correct

https://api.telegram.org/bot<token>/getWebhookInfo

Start the container

docker run -p 80:8080 --name chatbot -dit \
    -e BOT_TOKEN=your_telegram_bot_token \
    -e API= \
    -e API_URL= \
    -v ./user_configs:/home/user_configs \
    yym68686/chatgpt:latest

Or if you want to use Docker Compose, here is a docker-compose.yml example:

version: "3.5"
services:
  chatgptbot:
    container_name: chatgptbot
    image: yym68686/chatgpt:latest
    environment:
      - BOT_TOKEN=
      - API=
      - API_URL=
    volumes:
      - ./user_configs:/home/user_configs
    ports:
      - 80:8080

Run Docker Compose container in the background

docker-compose pull
docker-compose up -d

# uni-api
docker-compose -f docker-compose-uni-api.yml up -d

Package the Docker image in the repository and upload it to Docker Hub

docker build --no-cache -t chatgpt:latest -f Dockerfile.build --platform linux/amd64 .
docker tag chatgpt:latest yym68686/chatgpt:latest
docker push yym68686/chatgpt:latest

One-Click Restart Docker Image

set -eu
docker pull yym68686/chatgpt:latest
docker rm -f chatbot
docker run -p 8080:8080 -dit --name chatbot \
-e BOT_TOKEN= \
-e API= \
-e API_URL= \
-e GOOGLE_API_KEY= \
-e GOOGLE_CSE_ID= \
-e claude_api_key= \
-v ./user_configs:/home/user_configs \
yym68686/chatgpt:latest
docker logs -f chatbot

This script is for restarting the Docker image with a single command. It first removes the existing Docker container named "chatbot" if it exists. Then, it runs a new Docker container with the name "chatbot", exposing port 8080 and setting various environment variables. The Docker image used is "yym68686/chatgpt:latest". Finally, it follows the logs of the "chatbot" container.

Run the robot directly from the source code without using docker, Clone the repository:

git clone --recurse-submodules --depth 1 -b main --quiet https://github.com/yym68686/ChatGPT-Telegram-Bot.git

Install Dependencies:

pip install -r requirements.txt

Set Environment Variables:

export BOT_TOKEN=
export API=

Run:

python bot.py

The robot supports multiple plugins, including: DuckDuckGo and Google search, URL summary, ArXiv paper summary, DALLE-3 drawing, and code interpreter, etc. You can enable or disable these plugins by setting environment variables.

• How to develop a plugin?

All the code related to the plugin is in the git submodule ModelMerge within this repository. ModelMerge is an independent repository I developed to handle API requests, conversation history management, and other functionalities. When you clone this repository using the --recurse-submodules parameter, ModelMerge will be automatically downloaded locally. All the plugin code is located in this repository at the relative path ModelMerge/src/ModelMerge/plugins. You can add your own plugin code in this directory. The plugin development process is as follows:

1. Create a new Python file in the ModelMerge/src/ModelMerge/plugins directory, for example, myplugin.py. In the ModelMerge/src/ModelMerge/plugins/__init__.py file, import your plugin, for example, from .myplugin import MyPlugin.

2. In the ModelMerge/src/ModelMerge/tools/chatgpt.py file, add your plugin OpenAI tool format detailed request body to the function_call_list variable. The Claude Gemini tool does not require additional writing; you only need to fill in the OpenAI format tool request body. The program will automatically convert to Claude/Gemini tool format when requesting the Gemini or Claude API. function_call_list is a dictionary where the key is the name of the plugin, and the value is the request body of the plugin. Please ensure that the key names in the function_call_list dictionary are unique and do not duplicate the existing plugin key names.

3. Add key-value pairs to the PLUGINS dictionary in ModelMerge/src/ModelMerge/plugins/config.py, where the key is the name of the plugin and the value is the environment variable of the plugin and its default value. This default value acts as the switch for the plugin. If the default value is True, the plugin is enabled by default. If the default value is False, the plugin is disabled by default and needs to be manually enabled by the user in the /info command.

4. Finally, in the functions get_tools_result_async inside ModelMerge/src/ModelMerge/plugins/config.py, add the code for invoking the plugin. When the robot needs to call the plugin, it will call this function. You need to add the plugin invocation code inside this function.

After completing the above steps, your plugin can be used in the bot. 🎉

• What is the use of the WEB_HOOK environment variable? How should it be used?

WEB_HOOK is a webhook address. Specifically, when a Telegram bot receives a user message, it sends the message to the Telegram server, which then forwards the message to the server at the WEB_HOOK address set by the bot. Therefore, when a message is sent to the bot, the bot executes the processing program almost immediately. Receiving messages via WEB_HOOK results in faster response times than when WEB_HOOK is not set.

When deploying a bot using platforms like Zeabur, Replit, or Koyeb, these platforms provide you with a domain name that you need to fill in the WEB_HOOK, so the bot can receive user messages. Of course, not setting WEB_HOOK is also possible, but the bot's response time will be slightly longer, although the difference is not significant, so generally setting WEB_HOOK is not necessary.

When deploying a bot on a server, you need to use reverse proxy tools like nginx or caddy to forward messages sent by the Telegram server to your server, so the bot can receive user messages. Therefore, you need to set WEB_HOOK to your server's domain name and forward the traffic requesting WEB_HOOK to the server and corresponding port where the bot is located. For example, in caddy, you can configure it like this in the caddy configuration file /etc/caddy/Caddyfile:

your_webhook_domain.com {
    reverse_proxy localhost:8082
}

• Why can't I use Google search?

By default, DuckDuckGo search is provided. The official API for Google search needs to be applied for by the user. It can provide real-time information that GPT could not answer before, such as today's trending topics on Weibo, today's weather in a specific location, and the progress of a certain person or news event.

• Why can't I use the search function even though I added the Google search API?

There are two possibilities:

1. Only large language model (LLM) APIs that support tool usage can use the search function. Currently, this project only supports the search function for APIs of the OpenAI, Claude, and Gemini series models. APIs from other model providers are not supported for tool usage in this project at the moment. If you have a model provider you wish to adapt, you can contact the maintainer.

2. If you are using the APIs of OpenAI, Claude, and Gemini series models but cannot use the search function, it may be because the search function is not enabled. You can check whether the search function is enabled by clicking on preferences through the /info command.

3. If you are using the API of OpenAI, Claude, and Gemini series models, please ensure you are using the official API. If you are using a third-party relay API, the provider may be offering you the API through web scraping. APIs provided through web scraping cannot use tools use, meaning that all plugins of this project cannot be used. If you confirm that you are using the official API and still cannot search successfully, please contact the developer.

• How do I switch models?

You can switch between GPT3.5/4/4o, and other models using the "/info" command in the chat window.

• Can it be deployed in a group?

Yes, it supports whitelist to prevent abuse and information leakage.

• Why can't the bot talk when I add it to the group?

If this is the first time you add the bot to a group chat, you need to set the group privacy to disable in botfather, then remove the bot from the group chat and re-add it to use it normally.

The second method is to set the bot as an administrator, so the bot can be used normally. However, if you want to add the bot to a group chat where you are not an administrator, the first method is more suitable.

Another possibility is that the GROUP_LIST set is not the current group chat ID. Please check if GROUP_LIST is set; GROUP_LIST is the group ID, not the group name. The group ID starts with a minus sign followed by a string of numbers.

• How do the settings of GROUP_LIST, ADMIN_LIST, and whitelist affect the behavior of the bot?

If whitelist is not set, everyone can use the bot. If whitelist is set, only users in the whitelist can use the bot. If GROUP_LIST is set, only groups in the GROUP_LIST can use the bot. If both whitelist and GROUP_LIST are set, everyone in the group can use the bot, but only users in the whitelist can privately chat with the bot. If ADMIN_LIST is set, only users in the ADMIN_LIST can use the /info command to change the bot's settings. If ADMIN_LIST is not set, everyone can use the /info command to change the bot's configuration.

• How should I set the API_URL?

The API_URL supports all suffixes, including: https://api.openai.com/v1/chat/completions, https://api.openai.com/v1, and https://api.openai.com/. The bot will automatically allocate different endpoints based on different uses.

• Is it necessary to configure the web_hook environment variable?

The web_hook is not a mandatory environment variable. You only need to set the domain name (which must be consistent with WEB_HOOK) and other environment variables as required for your application's functionality.

• I deployed a robot with docker compose. If the documentation is placed on the server locally, which directory should it be mounted to in order to take effect? Do I need to set additional configurations and modify the code?

You can directly send the documentation to the robot through the chat box, and the robot will automatically parse the documentation. To use the documentation dialogue function, you need to enable the historical conversation feature. There is no need for additional processing of the documentation.

• I still can't get it to work... I want to use it in a group, I've set the ADMIN_LIST to myself, and the GROUP_LIST to that group, with the whitelist left empty. However, only I can use it in that group, other members in the group are prompted with no permission, what's going on?

Here's a troubleshooting guide: Please carefully check if the GROUP_LIST is correct. The ID of a Telegram group starts with a negative sign followed by a series of numbers. If it's not, please use this bot bot to reacquire the group ID.

• I've uploaded a document, but it's not responding based on the content of the document. What's going on?

To use the document question and answer feature, you must first enable the history record. You can turn on the history record through the /info command, or by setting the environment variable PASS_HISTORY to be greater than to 2 to enable the history record by default. Please note that enabling the history record will incur additional costs, so this project does not enable the history record by default. This means that the question and answer feature cannot be used under the default settings. Before using this feature, you need to manually enable the history record.

• After setting the NICK, there's no response when I @ the bot, and it only replies when the message starts with the nick. How can I make it respond to both the nick and @botname?

In a group chat scenario, if the environment variable NICK is not set, the bot will receive all group messages and respond to all of them. Therefore, it is necessary to set NICK. After setting NICK, the bot will only respond to messages that start with NICK. So, if you want to @ the bot to get a response, you just need to set NICK to @botname. This way, when you @ the bot in the group, the bot will detect that the message starts with @botname, and it will respond to the message.

• How many messages will the history keep?

All other models use the official context length settings, for example, the gpt-3.5-turbo-16k context is 16k, the gpt-4o context is 128k, and the Claude3/3.5 context is 200k. This limitation is implemented to save user costs, as most scenarios do not require a high context.

• How to delete the default model name from the model list?

You can use the CUSTOM_MODELS environment variable to complete it. For example, if you want to add gpt-4o and remove the gpt-3.5 model from the model list, please set CUSTOM_MODELS to gpt-4o,-gpt-3.5. If you want to delete all default models at once, you can set CUSTOM_MODELS to -all,gpt-4o.

• How does conversation isolation specifically work?

Conversations are always isolated based on different windows, not different users. This means that within the same group chat window, the same topic, and the same private chat window, it is considered the same conversation. CHAT_MODE only affects whether configurations are isolated. In multi-user mode, each user's plugin configurations, preferences, etc., are independent and do not affect each other. In single-user mode, all users share the same plugin configurations and preferences. However, conversation history is always isolated. Conversation isolation is to protect user privacy, ensuring that users' conversation history, plugin configurations, preferences, etc., are not visible to other users.

• Why hasn't the Docker image been updated for a long time?

The Docker image only stores the runtime environment of the program. Currently, the runtime environment of the program is stable, and the environment dependencies have hardly changed, so the Docker image has not been updated. Each time the Docker image is redeployed, it will pull the latest code, so there is no need to worry about the Docker image update issue.

• Why does the container report an error "http connect error or telegram.error.TimedOut: Timed out" after starting?

This issue is likely caused by the server deploying Docker being unable to connect to the Telegram server or the instability of the Telegram server.

1. In most cases, restarting the service, checking the server network environment, or waiting for the Telegram service to recover will suffice.
2. Additionally, you might try communicating with the Telegram server via web hook, which might solve the problem.

• How to make docker retry infinitely instead of stop at beginning?

The --restart unless-stopped parameter in Docker sets the container's restart policy. Specifically:

1. unless-stopped: This policy means that the container will automatically restart if it stops, except when it is manually stopped. In other words, if the container stops due to an error or system reboot, it will automatically restart. However, if you manually stop the container (e.g., using the docker stop command), it will not restart on its own. This parameter is particularly useful for services that need to run continuously, as it ensures that the service will automatically recover from unexpected interruptions without requiring manual intervention.

2. Example: Suppose you have a Docker container running a web server, and you want it to restart automatically if it crashes or if the system reboots, but not if you manually stop it. You can use the following command:

docker run -d --name my-web-server -p 80:80 --restart unless-stopped my-web-server-image

In this example, the web server container named my-web-server will restart automatically unless you manually stop it.

• Switching models, do I need to re-enter the prompt?

Yes, because switching models will reset the history, so you need to re-enter the prompt.

• What is the appropriate value for PASS_HISTORY?

The number of PASS_HISTORY is strictly equal to the number of messages in the conversation history. The recommended value is 2, because the system prompt occupies one message count. If set to 0, PASS_HISTORY will automatically reset to 2 to ensure the conversation proceeds normally. When PASS_HISTORY is less than or equal to 2, the bot's behavior can be regarded as only remembering the current conversation, i.e., one question and one answer, and it will not remember the content of the previous Q&A next time. There is no limit to the maximum value of PASS_HISTORY, but please note that the more messages in the conversation history, the higher the cost of each conversation will be. When PASS_HISTORY is not set, the default value is 9999, indicating that the number of messages in the conversation history is 9999.

• Can Bot tokens have multiple tokens?

No, in the future it will support multiple Bot Tokens.

• How to use robot commands?

1. /info: The robot /info command can view the robot's configuration information, including the current model in use, API URL, API key, etc. It can also change the robot's display language, preferences, and plugin settings.

2. /start: The robot /start command can view the robot's usage instructions, usage methods, and function introduction. You can set the API key using the /start command. If you have an official OpenAI API key, please use the following command: /start your_api_key. If you are using a third-party API key, please use the following command: /start https://your_api_url your_api_key.

3. /reset: The robot /reset command can clear the robot's conversation messages and force the robot to stop generating replies. If you want to reset the system prompt, please use the following command: /reset your_system_prompt. However, the /reset command will never restore the robot's display language, preferences, plugin settings, model in use, API URL, API key, system prompt, etc.

• What to do if Koyeb deployment fails?

Koyeb's free service can be a bit unstable, so deployment failures are pretty common. You might want to try redeploying, and if that doesn't work, consider switching to another platform. 😊

• Why does the default model name reappear after I use CUSTOM_MODELS to delete it, and then check again with the /info command?

If you deployed using docker-compose.yml, do not add quotes around the value of CUSTOM_MODELS. Incorrect usage: CUSTOM_MODELS="gpt-4o,-gpt-3.5", otherwise it will cause environment variable parsing errors, resulting in the default model name reappearing. The incorrect way will be parsed as deleting the gpt-3.5" model, which will cause the default model name gpt-3.5 not to be deleted. The correct way to write it is: CUSTOM_MODELS=gpt-4o,-gpt-3.5.

https://core.telegram.org/bots/api

https://github.com/acheong08/ChatGPT

https://github.com/franalgaba/chatgpt-telegram-bot-serverless

https://github.com/gpchelkin/scdlbot/blob/d64d14f6c6d357ba818e80b8a0a9291c2146d6fe/scdlbot/__main__.py#L8

The markdown rendering of the message used is another project of mine.

duckduckgo AI: https://github.com/mrgick/duck_chat

We are grateful for the support from the following sponsors:

• @fasizhuanqian: 300 USDT

• @ZETA: $380

• @yuerbujin: ¥1200

• @RR5AM: ¥300

• @IKUNONHK: 30 USDT

• @miya0v0: 30 USDT

• @Zeabur: $25

• @Bill_ZKE: 20 USDT

• @wagon_look: ¥50

If you would like to support our project, you can sponsor us through the following methods:

1. PayPal

2. USDT-TRC20, USDT-TRC20 Wallet Address: TLFbqSv5pDu5he43mVmK1dNx7yBMFeN7d8

3. WeChat

4. Alipay

Thank you for your support!

This project is licensed under GPLv3, which means you are free to copy, distribute, and modify the software, as long as all modifications and derivative works are also released under the same license.