💬 walini — WhatsApp Chatbot Dashboard

A rule-based WhatsApp chatbot with a PHP web dashboard. The bot handles incoming messages by matching keywords and navigating numbered menus, then auto-replies with text or images. The dashboard lets you manage keywords, menus, AI config, logs, and bot settings through a browser — no code editing required.

Stack

• Bot Engine: Node.js + @whiskeysockets/baileys
• Database: SQLite3 via sql.js
• Dashboard: PHP 7.4 + HTML/CSS/JS vanilla
• Internal API: Express.js (Node.js) ↔ PHP via cURL
• AI: OpenAI-compatible API (Groq, OpenRouter, OpenAI, dll)

---

🚀 Installation

1. Clone & install dependencies

npm install

2. Configure environment

cp .env.example .env

Then edit .env as needed:

# Port used by the Node.js bot API (default: 3001)BOT_API_PORT=3001# URL used by PHP to call the bot API# Must be 127.0.0.1 (loopback) — NOT 0.0.0.0BOT_API_URL=http://127.0.0.1:3001# API key shared between the PHP dashboard and the bot — MUST be changed in productionBOT_API_KEY=changeme-secret-key# Dashboard login password — MUST be changed in productionDASHBOARD_PASSWORD=admin123# Optional: bind host (default 127.0.0.1)# BIND_HOST=127.0.0.1

⚠️Important: Always change BOT_API_KEY and DASHBOARD_PASSWORD before deploying to a public server.

3. Start everything (recommended)

chmod +x start.sh
bash start.sh

The script will automatically:

• Check that node, npm, and php are installed
• Run npm install if node_modules is missing
• Start the Node.js bot (port BOT_API_PORT, default 3001)
• Start the PHP dashboard (port 8080)
• Save logs to the logs/ folder
• Shut down both services cleanly on Ctrl+C

4. Or run manually

# Terminal 1 — Node.js bot
npm start
# or for development (auto-restart on change):
npm run dev
# Terminal 2 — PHP dashboard
php -S localhost:8080 -t web/

The bot will automatically create the SQLite database and seed sample data on first run.

5. Log in to the dashboard

1. Open your browser at http://localhost:8080
2. Log in with the password from .env (default: admin123)
3. Scan the QR code shown on the dashboard with WhatsApp on your phone

---

📁 Project Structure

walini/
├── bot/
│ ├── index.js # Main bot engine (Baileys)
│ ├── api.js # REST API for the dashboard
│ ├── database.js # SQLite helper functions
│ └── ai.js # AI chat handler (OpenAI-compatible)
├── database/
│ ├── schema.sql # Database schema + sample data
│ ├── ai.json # AI config (url, model, key, prefixes)
│ ├── ai.example.json # AI config template
│ └── chatbot.db # Database file (auto-generated)
├── web/ # PHP Dashboard
│ ├── config.php # PHP config + shared API helpers
│ ├── index.php # Main dashboard + stats
│ ├── keywords.php # Manage keyword auto-replies
│ ├── menus.php # Manage interactive menus
│ ├── ai.php # AI configuration
│ ├── placeholders.php # Placeholder reference
│ ├── logs.php # Message log viewer
│ ├── settings.php # Bot settings
│ ├── login.php # Login page
│ ├── logout.php # Logout
│ ├── debug.php # Connection diagnostics (delete after setup)
│ ├── api/
│ │ └── proxy.php # PHP → Node.js API proxy
│ ├── partials/
│ │ ├── sidebar.php
│ │ └── topbar.php
│ └── assets/
│ ├── css/style.css
│ └── js/app.js
├── logs/ # Runtime logs (auto-generated by start.sh)
│ ├── bot.log
│ └── php.log
├── uploads/ # Uploaded images + received media
│ └── received/ # Files saved by #update keyword
├── .baileys_auth/ # Baileys session files (auto-generated)
├── .env # Environment config (create from .env.example)
├── .env.example # Environment template
├── start.sh # One-command startup script
├── package.json
└── README.md

---

⚙️ How the Bot Works

Message processing flow:

Incoming message
│
├─ Location message?
│ └─ Save to session + send location_reply (if set) → STOP
│
├─ Caption matches #update + media attached?
│ └─ Save file to uploads/received/ → reply success/failure → STOP
│
├─ Starts with AI prefix? (e.g. "bot: ", "ai: ")
│ └─ Forward to configured AI → send reply → STOP
│
├─ Menu trigger word? (default: "menu")
│ └─ Show main menu
│
├─ User is in an active menu session?
│ └─ Process number selection
│
├─ Matches a keyword?
│ └─ Send keyword reply
│
├─ Number at root level?
│ └─ Process menu selection
│
├─ AI fallback enabled?
│ └─ Forward to AI → send reply
│
└─ Send static fallback message

Messages are silently ignored if:

• Sent by the bot itself
• From status@broadcast
• From a group chat (@g.us)
• bot_active is set to 0 in the dashboard

Keyword match types:

• Partial — message contains the keyword (case-insensitive)
• Exact — message is exactly the keyword

Menus:

• Number 0 always means "Back" or "Exit"
• A menu item with no reply text = it has sub-menu children
• Menu sessions time out after a configurable period (default: 30 minutes)

Placeholders:

All reply texts (keywords, menus, AI output, location reply, #update replies) support placeholders. Full list at web/placeholders.php. Examples:

Placeholder	Value
{nama}	Sender's WhatsApp display name
{nomor}	Sender's phone number
{jam} / {tanggal} / {hari}	Current time / date / day
{lokasi_url}	Google Maps link from location message
{lokasi_terakhir_url}	Google Maps link from last saved location
{bot_name}	Bot name from settings
{foto}	Sender's profile picture URL
{status}	Sender's WhatsApp about/status

AI Features:

• Prefix trigger — user starts message with a configured prefix (e.g. bot: apa itu AI?)
• Fallback AI — if no keyword/menu matches, the message is forwarded to AI instead of showing the static fallback
• Configured via dashboard → AI Chat, or directly in database/ai.json
• Compatible with any OpenAI-format API (Groq, OpenRouter, OpenAI, local LLM, etc)

#update — Media Save:

• User sends any media (image/video/audio/document) with caption #update
• Bot saves the file to uploads/received/ and replies with a configurable success/failure message
• Configurable per allowed file type, max 20MB
• Voice notes (PTT) are always skipped

---

🔒 Security

• Change BOT_API_KEY and DASHBOARD_PASSWORD in .env before deploying
• Keep BOT_API_PORT (default 3001) private — it is for internal PHP ↔ Node communication only
• Only expose ports 80/443 (the PHP dashboard) to the public
• Never commit .env or database/ai.json (contains your AI API key) to version control
• Delete web/debug.php once setup is confirmed working

---

🐛 Troubleshooting

Bot won't connect / need to re-scan QR:

# Delete the Baileys session and scan again
rm -rf .baileys_auth/
bash start.sh

Dashboard can't reach the bot:

• Make sure the bot is running (bash start.sh or npm start)
• Open http://localhost:8080/debug.php for a full connection diagnostic
• Check that BOT_API_URL and BOT_API_PORT in .env match what is actually running
• Check that port 3001 is not blocked by a firewall

AI not responding:

• Check that database/ai.json exists and has url, model, and key set
• Configure via dashboard → AI Chat
• Test the API key directly with curl if unsure

Port already in use:

# Check what is using port 3001 or 8080
ss -tlnp | grep -E '3001|8080'# Or check the PID files from the last run
cat .bot.pid
cat .php.pid

Duplicate keywords on startup:

node bot/cleanup-db.js