chatgpt-telegram-bot

Prerequisites

Before you begin, make sure you have the following installed and ready:

• Python 3.10+ — Download Python
• Docker and Docker Compose — Recommended deployment method. Install Docker
• Git — To clone the repository
• A Telegram account — To create and test the bot
• An OpenAI account — With API access and available credit

---

Get Your API Keys

1. OpenAI API Key

1. Go to https://platform.openai.com/api-keys
2. Sign in or create an account
3. Click "Create new secret key"
4. Give it a name (e.g., chatgpt-telegram-bot) and click Create
5. Copy the key immediately — it will not be shown again
6. Ensure your account has billing set up at https://platform.openai.com/account/billing, as the bot uses paid API calls

2. Telegram Bot Token

1. Open Telegram and search for @BotFather
2. Start a chat and send the command /newbot
3. Follow the prompts: provide a display name (e.g., My GPT Bot) and a username ending in bot (e.g., my_gpt_assistant_bot)
4. BotFather will respond with a token in the format 123456789:ABCDefgh...
5. Copy and save this token securely

---

Installation

Option A: Docker (Recommended)

# Clone the repository
git clone https://github.com/karfly/chatgpt_telegram_bot.git
cd chatgpt_telegram_bot

# Copy the example config files
cp config/config.example.yml config/config.yml
cp config/chat_modes.yml config/chat_modes.yml  # already present, no copy needed

Option B: Local Python Environment

# Clone the repository
git clone https://github.com/karfly/chatgpt_telegram_bot.git
cd chatgpt_telegram_bot

# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate        # On Windows: venv\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

# Copy the example config
cp config/config.example.yml config/config.yml

---

Configuration

Open config/config.yml in a text editor and fill in your values. The file uses YAML format — indentation matters.

nano config/config.yml   # or use any editor you prefer

The key fields to configure:

| Variable | Description | Where to get it | |----------|-------------|-----------------| | telegram_token | Your Telegram bot's API token | @BotFather — received when creating the bot | | openai_api_key | Your OpenAI secret API key | platform.openai.com/api-keys | | allowed_telegram_usernames | List of Telegram usernames permitted to use the bot (leave empty [] to allow all users) | Your own Telegram username, found in Telegram Settings | | new_dialog_timeout | Seconds of inactivity before a new dialog starts automatically | Set to a number like 600 (10 minutes); no external source needed | | openai_api_base | Base URL for the OpenAI API (optional) | Leave as default unless using a compatible alternative like LocalAI | | mongodb_uri | MongoDB connection string for storing conversation history | Set up a local or hosted MongoDB instance (e.g., MongoDB Atlas) | | models.available_text_models | List of GPT models the bot can use | Check available models at platform.openai.com/docs/models |

A minimal working example of config/config.yml:

telegram_token: "123456789:ABCDefghIjklMnoPqrsTuvwXyz"
openai_api_key: "sk-..."
allowed_telegram_usernames: ["your_telegram_username"]
mongodb_uri: "mongodb://mongo:27017"

Note: You can also customize chat modes by editing config/chat_modes.yml. Each mode defines a system prompt and display name. The default file includes 15 pre-built modes.

---

Running the Bot

Option A: Docker Compose (Recommended)

Docker Compose will start both the bot and a MongoDB instance automatically.

# Start all services in the background
docker compose up --build -d

# View live logs
docker compose logs -f

To stop the bot:

docker compose down

Option B: Local Python

Make sure MongoDB is running locally on port 27017 before starting the bot. Then:

# Activate your virtual environment if not already active
source venv/bin/activate

# Run the bot
python bot/bot.py

You should see log output in the terminal confirming the bot has connected to Telegram.

---

Testing

Once the bot is running, perform a quick smoke test:

1. Open Telegram and search for your bot by the username you registered with BotFather
2. Start a conversation by clicking Start or sending /start
3. Send the /help command — the bot should reply with a list of available commands
4. Send a plain text message, such as:

   What is the capital of France?
   

   The bot should stream back a response within a few seconds
5. Run /balance to confirm your OpenAI API key is valid and the bot can reach the OpenAI API
6. Run /settings to verify model selection is working

If all five steps succeed, your bot is correctly configured and operational.

---

Troubleshooting

| Problem | Likely cause | Fix | |---------|--------------|-----| | Bot does not respond to messages | telegram_token is incorrect or the bot process has crashed | Double-check the token in config/config.yml; run docker compose logs -f or check terminal output for error messages | | openai.AuthenticationError in logs | openai_api_key is invalid, expired, or missing | Regenerate the key at platform.openai.com/api-keys and update config/config.yml | | pymongo.errors.ConnectionFailure | Bot cannot connect to MongoDB | Ensure MongoDB is running; if using Docker Compose, confirm the mongo service started with docker compose ps | | Bot responds to no one, even you | allowed_telegram_usernames is set and your username is not listed | Add your Telegram username to the list in config/config.yml, or set it to [] to allow all users | | Voice messages are not transcribed | OpenAI Whisper API is not accessible or the API key lacks permissions | Confirm your OpenAI account has access to the Whisper API and that your key is active | | docker compose command not found | Using an older Docker version that uses docker-compose (with a hyphen) | Try docker-compose up --build -d instead, or upgrade Docker to a version that includes Compose v2 |

If you encounter an issue not listed here, check the project's GitHub Issues page or consult the project README for additional details.