──「 𝗜𝗗 𝗖𝗛𝗔𝗧𝗕𝗢𝗧 」──

An Advanced, Asynchronous Telegram AI Chatbot powered by Google Gemini and Pyrogram

---

Deploy To Heroku 🚀

🌟 Key Features

• 🤖 Google Gemini AI Engine: Intelligent, context-aware conversations powered by Google's generative models (gemini-pro).
• 💬 Multi-Turn Chat History: Retains conversational context per user/chat for coherent long discussions.
• 👥 Group & DM Support: Works seamlessly in both private direct messages and group chats.
• 🎛️ Group Chatbot Toggle: Admins can easily enable or disable AI auto-replies in groups (/chatbot on / /chatbot off).
• 📢 Broadcast System: Broadcast text, media, or pinned messages across all registered users and chats with detailed delivery stats.
• 📊 Real-Time Analytics & Stats: View total users, total groups, system uptime, and database metrics.
• ⚡ Asynchronous Architecture: Fully asynchronous I/O using Pyrogram v2, Motor (async MongoDB), and aiohttp for ultra-fast response times.
• 🔒 Role-Based Access Control: Protected owner/admin commands to ensure bot security.
• 🐳 Docker & Heroku Ready: Pre-configured Procfile, Dockerfile, heroku.yml, and app.json for one-click deployments.

---

🚀 One-Click Deploy to Heroku

Deploying your own instance of ID Chatbot to Heroku is quick and simple:

Note

Make sure you enable the worker dyno in your Heroku app's Resources tab after deploying.

---

🛠️ Environment Variables

Configure the following environment variables in your .env file or hosting service dashboard:

Variable	Type	Required	Default	Description
BOT_TOKEN	String	Yes	—	Telegram Bot token obtained from @BotFather
API_ID	Integer	Yes	—	Telegram API ID from my.telegram.org
API_HASH	String	Yes	—	Telegram API Hash from my.telegram.org
MONGO_URL	String	Yes	—	MongoDB connection URI string (e.g. MongoDB Atlas)
OWNER_ID	Integer	Yes	—	Telegram numeric User ID of the bot owner
GEMINI_API_KEY	String	Yes	—	Google Gemini API Key from Google AI Studio
BOT_NAME	String	No	ID Chatbot	Display name of the bot
BOT_USERNAME	String	No	None	Telegram username of the bot (without @)
SUPPORT_GROUP	String	No	None	Telegram link or username for the support group
SUPPORT_CHANNEL	String	No	None	Telegram link or username for the updates channel

---

📖 Commands List

👤 User & Group Commands

Command	Arguments	Description
/start	None	Start the bot and receive a welcome message with quick actions
/help	None	View help documentation and list of available commands
/ping	None	Check the bot latency and system status
/chatbot	on / off	Toggle AI chatbot mode in the current group chat (Admins only)
/clear	None	Clear conversational history / context with the AI

👑 Owner & Admin Commands

Command	Arguments	Description
/stats	None	View total registered users, active chats, server uptime, and database stats
/broadcast	<message> / Reply	Broadcast a message or media to all users and group chats
/bchat	<message> / Reply	Broadcast exclusively to registered group chats
/buser	<message> / Reply	Broadcast exclusively to private chat users
/users	None	View detailed count and list of active bot users
/chats	None	View detailed count and list of active connected groups

---

🔑 How to Obtain Credentials

1. Telegram API_ID & API_HASH

1. Log in with your Telegram phone number at https://my.telegram.org.
2. Navigate to API Development Tools.
3. Fill out the application form (Title and Short Name).
4. Copy your api_id (numeric) and api_hash (alphanumeric string).

2. Telegram BOT_TOKEN

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the on-screen instructions.
3. Choose a name and unique username ending in bot.
4. Copy the HTTP API token provided by BotFather.

3. Telegram OWNER_ID

1. Message @userinfobot or @MissRose_bot (send /id).
2. Copy your numeric user ID (e.g., 123456789).

4. MongoDB MONGO_URL

1. Create a free account on MongoDB Atlas.
2. Create a free shared cluster (M0 sandbox).
3. Under Database Access, create a user with read/write permissions.
4. Under Network Access, add IP address 0.0.0.0/0 (allow access from anywhere).
5. Go to Clusters > Connect > Drivers > Select Python driver.
6. Copy the connection string format:

   mongodb+srv://<username>:<password>@cluster0.mongodb.net/?retryWrites=true&w=majority
   

   (Replace <username> and <password> with your database user credentials).

5. Google Gemini GEMINI_API_KEY

1. Visit Google AI Studio.
2. Sign in with your Google account.
3. Click on Get API Key and generate a new key for your project.
4. Copy the generated API key.

---

💻 Manual Deployment & Installation

Option 1: Local / VPS Installation

1. Clone the repository:

   git clone https://github.com/yourusername/idchatbot.git
   cd idchatbot

2. Set up a Python Virtual Environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: .\venv\Scripts\activate

3. Install Dependencies:

   pip install -U pip
   pip install -r requirements.txt

4. Set Up Environment Variables:

   cp sample.env .env
   # Edit .env with your favorite editor (e.g., nano, vim, or code)
   nano .env

5. Run the Bot:

   python3 -m bot

---

Option 2: Docker Deployment

1. Build Docker Image:

   docker build -t idchatbot .

2. Run Docker Container:

   docker run -d --name idchatbot --env-file .env idchatbot

---

📁 Project Structure

idchatbot/
├── bot/
│   ├── __init__.py           # Bot client & DB initialization
│   ├── config.py             # Config variables & environment loaders
│   ├── database/             # MongoDB async models (users, chats, settings)
│   │   ├── chats_db.py
│   │   ├── settings_db.py
│   │   └── users_db.py
│   ├── helpers/              # Decorators, utility helpers, keyboards
│   │   ├── decorators.py
│   │   └── utils.py
│   └── plugins/              # Message handlers, commands & AI logic
│       ├── admin.py
│       ├── broadcast.py
│       ├── chatbot.py
│       └── start.py
├── .gitignore                # Git ignored patterns
├── Dockerfile                # Docker image definition
├── Procfile                  # Heroku worker process definition
├── README.md                 # Project documentation
├── app.json                  # Heroku one-click deploy manifest
├── heroku.yml                # Heroku container build configuration
├── requirements.txt          # Python dependencies
├── runtime.txt               # Heroku Python runtime version
└── sample.env                # Environment template

---

🤝 Credits & Acknowledgements

• Pyrogram — Elegant, modern Telegram MTProto API framework for Python.
• Google Generative AI — Next-generation generative AI SDK from Google.
• Motor — Asynchronous Python driver for MongoDB.
• Heroku — Cloud platform for effortless bot deployment.

---

Made with ❤️ by ID Chatbot Team