A full-featured WhatsApp bot for group management, AI chat, media tools, productivity, and fun — built on Baileys.
| Category | Highlights |
|---|---|
| 🧠 AI Chat | Groq (primary) + Gemini fallback — text rewriting, reply drafting, document analysis, voice summary |
| 🎨 Image Generation | Gemini → Cloudflare → Pollinations — text-to-image with automatic multi-provider fallback |
| 🗣️ Speech-to-Text | Groq Whisper — transcribe voice notes, auto-convert Urdu/Hindi to Roman script |
| 📥 Media & Downloads | YouTube, Spotify, Instagram, TikTok, Twitter, Facebook, Pinterest — audio, video, and more |
| 🎮 Games | Tic-Tac-Toe, Hangman, Bomb, Trivia |
| 😄 Fun | Jokes, quotes, roasts, compliments, shayari, memes, 8-ball, dare/truth, and more |
| 🛡️ Group Management | Anti-link, anti-badword, anti-sticker, warnings, bans, mute, kick, promote, demote |
| 👑 Owner Controls | Mode switching, broadcast, sudo, auto-read/typing, anti-call, anti-delete, OTA update |
| ⏰ Productivity | Reminders (relative, absolute, recurring), scheduled messages, snooze, polls, saved messages |
| 📊 Utilities | Calculator, weather (keyless), air quality, sunrise/sunset, name info, news (keyless), QR codes, screenshots, URL shortener, GitHub lookup |
| 🌐 Free APIs | Weather, AQI, sun times, news, and name-info all use no API keys — powered by Open-Meteo, Google News RSS, and agify/genderize/nationalize |
| 🎌 Anime & Textmaker | Anime image fetcher, styled text generator with 19+ font styles |
| 🖼️ Stickers | Image/video-to-sticker with crop, custom pack names, animated sticker support |
Optimus Bot
├── index.js # Entry point — pairing / session bootstrap
├── main.js # Message handler, dispatch, group protections
├── settings.js # Bot configuration (gitignored — copy settings.example.js)
├── lib/
│ ├── aiConfig.js # AI model IDs — single source of truth
│ ├── ai.js # Centralized AI client (Groq + Gemini)
│ ├── imageGeneration.js # Image provider fallback chain (Gemini → CF → Pollinations)
│ ├── messageStyle.js # Unified visual formatting system
│ ├── messageConfig.js # Shared contextInfo / newsletter config
│ ├── commandLoader.js # Dynamic command registration
│ ├── mode.js # Public/Private mode with caching
│ ├── isBanned.js # Ban system with in-memory cache
│ ├── afk.js # AFK system with in-memory cache
│ ├── weatherApi.js # Shared geocoding + weather + AQI helper (Open-Meteo, keyless)
│ ├── news.js # Google News RSS parser (keyless — top, topic, search)
│ ├── potSupervisor.js # PO-token provider supervisor (auto-restart, backoff)
│ ├── dlHealth.js # Download health monitor with push alerts
│ ├── productivity/
│ │ ├── scheduler.js # Reminder/message scheduler (recurring-aware)
│ │ ├── reminderStore.js # Reminder persistence (recurring, kind, snooze)
│ │ ├── timeParse.js # Time parser (relative/absolute/recurring)
│ │ └── dataStore.js # Generic JSON data-store helper
│ └── ... # Additional helpers
├── commands/
│ ├── admin/ # 51 group-management commands
│ ├── ai/ # 11 AI-powered commands
│ ├── anime/ # 5 anime image commands
│ ├── fun/ # 39 fun/entertainment commands
│ ├── general/ # 37 general utility commands (incl. news, productivity)
│ ├── group/ # 1 group command
│ ├── media/ # 14 media/download commands
│ ├── owner/ # 29 owner-only control commands
│ ├── textmaker/ # 1 styled text generator
│ └── utility/ # 30 utility commands (weather, aqi, sun, nameinfo, calc, qr, ...)
├── scripts/ # 25 smoke-test suites
├── data/ # Runtime state (gitignored — auto-created on first run)
└── session/ # WhatsApp session (gitignored)
Tech Stack: Node.js ≥ 18 · Baileys (WhatsApp Web API) · Axios · Sharp · FFmpeg · Groq API · Google Gemini API · Cloudflare Workers AI · Pollinations · Open-Meteo · Google News RSS
Optimus uses multiple AI providers with automatic fallback. Model IDs are centralized in lib/aiConfig.js — the single source of truth.
| Provider | Purpose | Default Model |
|---|---|---|
| Groq | Primary text chat | openai/gpt-oss-120b |
| Groq | Speech-to-text | whisper-large-v3-turbo |
| Gemini | Fallback text chat | gemini-2.5-flash |
| Gemini | Primary image generation | gemini-3.1-flash-image |
| Cloudflare | Image fallback #1 | @cf/black-forest-labs/flux-1-schnell |
| Pollinations | Image fallback #2 | flux (no API key required) |
Fallback chains:
- Text: Groq → Gemini
- Speech-to-Text: Groq Whisper
- Image: Gemini → Cloudflare → Pollinations
To change a model, edit lib/aiConfig.js directly. Run .aistatus as the bot owner to view the currently configured providers and models.
- Node.js ≥ 22.0.0
- FFmpeg — bundled via
ffmpeg-static; a system install is optional (seeDEPLOY.md§5) - A WhatsApp account for pairing
git clone https://github.com/CodeWithTayyab96/Optimus-Bot.git
cd Optimus-Bot
npm installOr skip the manual install and let the bot bootstrap itself. bootstrap.js installs
everything the bot needs — npm dependencies, the PO token provider (clone + build), and
yt-dlp plus its plugin — and only then starts the bot:
node bootstrap.js # install anything missing, then start
node bootstrap.js --deps-only # install anything missing, then exit
node bootstrap.js --check # report what would happen, change nothingOn a host or panel, use node bootstrap.js (or npm start) as the startup command.
If the startup command is node index.js, none of this runs and the extras are never
installed. Every step is idempotent and cheap once things are present, so it is safe to
leave in place permanently.
settings.js is committed and works out of the box — it ships with placeholders, so a fresh
clone runs with no manual copy step. Never put real API keys in it.
Put credentials in .env instead (gitignored):
cp .env.example .envThen fill in .env. Every value is optional — the bot starts without them, but the related
command won't work until it is set:
GROQ_API_KEY= # .ai / whisper transcription — console.groq.com
GEMINI_API_KEY= # .ai image generation — aistudio.google.com
CLOUDFLARE_ACCOUNT_ID= # image fallback #1 — dash.cloudflare.com → Workers AI
CLOUDFLARE_API_TOKEN=
GIPHY_API_KEY= # .gif
OMDB_API_KEY= # .imdb
TENOR_API_KEY= # .emojimix
TELEGRAM_BOT_TOKEN= # .stickertelegram — create your own with @BotFatherEach of these is read as process.env.X || '<placeholder>', so the environment always wins.
Non-secret options — prefix, bot name, owner number, channel links — are edited directly in
settings.js.
⚠️ Important:settings.jsis committed to this repository. Anything you put in it, including API keys, is published permanently in the git history. Keep secrets in.env.
node index.jsA pairing code will appear in the terminal. Enter it in WhatsApp → Settings → Linked Devices → Link a Device.
After the first pairing, the session is saved to session/ and subsequent restarts connect automatically.
Several features use completely free, no-API-key-required services:
| Feature | Command | Service |
|---|---|---|
| Weather + forecast | .weather <city> |
Open-Meteo |
| Air quality (AQI) | .aqi <city> |
Open-Meteo Air Quality |
| Sunrise / sunset | .sun <city> |
Open-Meteo |
| Name insights | .nameinfo <name> |
agify + genderize + nationalize |
| News (top, topic, search) | .news [topic|keyword] |
Google News RSS |
These work out of the box — no signup, no key, no configuration.
| Command | What it does |
|---|---|
.remind 10m Submit assignment |
Reminder in 10 minutes |
.remind 5pm Call mom |
Reminder at an absolute clock time |
.remind tomorrow 9am Meeting |
Reminder for tomorrow |
.remind daily 9am Standup |
Recurring daily reminder (auto-reschedules) |
.remind weekly mon 9am Sync |
Recurring weekly reminder |
.schedule 30m Standup in 5 |
Bot posts the message itself at the set time |
.schedule daily 7am Good morning |
Recurring scheduled message |
.snooze R001 10m |
Push a reminder back by 10 minutes |
.reminders |
List all pending reminders + scheduled messages |
.cancelreminder R001 |
Cancel a reminder or scheduled message |
| Command | What it does |
|---|---|
.update |
Pull latest from GitHub, backup/restore runtime state, restart |
.update check |
Dry run — show available commits/files without applying |
.update <zip-url> |
Update from a ZIP archive (for non-git deployments) |
The update system backs up data/, settings.js, and baileys_store.json before applying changes, then restores them — so mode, warnings, AFK, stats, and configuration survive updates.
Repo URL and branch are configurable via settings.updateRepoUrl / settings.updateBranch or UPDATE_REPO_URL / UPDATE_BRANCH environment variables.
npm testRuns 25 smoke-test suites + 363 Jest tests covering:
| Test | What it verifies |
|---|---|
check-help |
All commands appear in dynamic Help |
smoke-dispatch |
Command routing and prefix handling |
smoke-games |
Tic-Tac-Toe, Bomb game logic |
smoke-ai |
AI command metadata and error handling |
smoke-ai-config |
Centralized config structure and consumption |
smoke-cache |
isBanned / AFK / userGroupData caching |
smoke-models |
No dead/deprecated AI model IDs |
smoke-migration |
All legacy commands still registered |
smoke-update |
Runtime-state backup/restore across updates |
smoke-general |
General/utility commands, news, productivity |
smoke-media |
Media download command metadata |
smoke-menu |
Help menu rendering and categories |
smoke-* |
Category-specific UI, permissions, and behavior |
230 commands across 10 categories:
🛡️ Admin (51 commands)
antibadword · antigroupmention · antigroupstatus · antilink · antisticker · antitag · autosticker · ban · chatbot · clear · delete · demote · goodbye · grouplink · groupmanage · groupstatus · hidetag · kick · mention · mute · pending · promote · resetlink · resetwarn · tag · tagall · tagnotadmin · unban · unmute · warn · warnings · welcome · setgdesc / setgname / setgpp · and more
🧠 AI (11 commands)
gpt (gemini) · gptimage (gptimg, editimage, aiimage, gi) · imagine · magicstudio (magic, magicai, generate) · reply · rewrite · stt (totext) · study · summarize (tldr) · voicesummary (vsum)
🎮 Fun & Games (39 commands)
advice · bomb · character · compliment · dare · 8ball · fact · flirt · gayrate · gif · goodnight · hangman · insult · joke · meme · memesearch · motivate · pies · quote · riddle · roast · roseday · shayari · simp · tictactoe (ttt) · topmembers · trivia · truth · wasted · and more
📦 General (37 commands)
alive · attp · emojimix · getpp · github · groupinfo · groupstats · help · myactivity · news (headlines) · owner · ping · settings · simage · ss · staff · sticker · sticker-alt · stickercrop · stickertelegram · take · tts · translate · uptime · url · remind · reminders · cancelreminder · schedule (sched, schedulemsg) · snooze (snoozeremind) · poll · pollresult · save · saved · unsave
📥 Media (26 commands)
facebook · igs · img-blur · instagram · lyrics · pinterest · play · remini · removebg · song · spotify · tiktok · twitter · video · and more
👑 Owner (29 commands)
aistatus (aistat) · afk · anticall · antidelete · areact · autoread · autostatus · autotyping · block · broadcast · clearsession · cleartmp · jid · mode · pair · pmblocker · restart · setbotname · setmenuimage · setnewsletter · setprefix · sudo · unblock · update (.update check for dry-run) · and more
🔧 Utility (30 commands)
calc · qr · weather · aqi (air, airquality) · sun (sunrise, sunset, suntimes) · nameinfo (nameage, guessname, namelook) · and more
🎌 Anime & Textmaker
animu (anime image fetcher) · textmaker (19 font styles)
- Session credentials (
session/) are gitignored — never commit them - API keys in
settings.jsare gitignored — copysettings.example.jsinstead - Environment variables (
.env) supported for all credential fields - The
.aistatuscommand shows only model IDs, never API keys or tokens - Owner-only commands are enforced at the loader level
- See SECURITY.md for responsible-disclosure guidelines
See CONTRIBUTING.md for development setup, project conventions, and how to add new commands.
This project is licensed under the ISC License.
- Tayyab — Creator & maintainer
- Baileys — WhatsApp Web API library
- Groq — Fast AI inference
- Google Gemini — AI chat and image generation
- Cloudflare Workers AI — Image generation fallback
- Pollinations — Free image generation fallback
- Open-Meteo — Free weather and air-quality data
- Google News RSS — Free news headlines
This bot is provided for educational purposes only. It is not affiliated with, authorized, or endorsed by WhatsApp. Using automated tools with WhatsApp may result in account restrictions. Use at your own risk.