CERYA WA BOT

WhatsApp Bot Helpdesk & Interactive Catalog Assistant

Developed by ricnah

---

Overview

CERYA WA BOT is an automated WhatsApp helpdesk and interactive catalog system designed for customer support and product catalog delivery.

Built on the xshine-wa engine, it integrates interactive buttons, product carousels, local Retrieval-Augmented Generation (RAG) keyword search over structured JSON databases, Groq and OpenRouter language model fallback pipelines, 8-digit Pairing Code verification, and a post-order cooldown management system.

Note

This project is designed to be customizable for various business niches and comes pre-configured as a Virtual Customer Service assistant for TRAVELERA Tour & Travel.

---

Beginner Quick Start Guide

Follow these steps sequentially to set up and run the bot:

1. Prerequisites

Ensure Node.js (version 20.0.0 or higher, recommended 22+) is installed on your machine or VPS.

• Verify your Node.js version in terminal:

  node -v

---

2. Open Terminal in Project Directory

Open your terminal (Command Prompt, PowerShell, VS Code Terminal, or Linux Terminal) and make sure you are inside the project folder.

---

3. Install Dependencies (npm install)

Important

This step is required on first setup. Skipping this step will result in missing package errors (such as Cannot find package 'dotenv').

Run the following command in your terminal:

npm install

Wait until all dependency packages finish installing.

---

4. Configure Environment Variables (.env)

1. Copy .env.example and rename it to .env (or create a new .env file).
2. Open .env and fill in your API keys:

# Get your API key from https://console.groq.com/keys
GROQ_API_KEY=gsk_your_groq_api_key_here

# Optional fallback: Get your API key from https://openrouter.ai/keys
OPENROUTER_API_KEY=sk-or-v1-your_openrouter_api_key_here

---

5. Set Owner Number (config.js)

Open config.js and set your WhatsApp number on the PRIMARY_OWNER_NUMBER variable:

const PRIMARY_OWNER_NUMBER = "62812xxxxxxxx"; // Your WhatsApp number with country code (e.g., starting with 62)

This number is automatically synchronized across database records and used for Pairing Code verification.

---

6. Start the Bot (npm start)

Run the bot using:

npm start

(Or node index.js)

---

7. Link Your WhatsApp Account

Method 1: Pairing Code (Default & Recommended)

1. The terminal will display an 8-character verification code (example: CERY-A123).
2. Open WhatsApp on your phone -> Go to Settings / Three-Dots Menu.
3. Select Linked Devices.
4. Select Link a Device -> Tap "Link with phone number instead" at the bottom.
5. Enter the 8-character verification code shown in the terminal.
6. WhatsApp will automatically connect.

Method 2: QR Code Scan

1. In db/config.json, change "usePairingCode": false.
2. Run npm start.
3. Scan the QR code displayed in the terminal using Linked Devices on your phone.

---

Features

Dual Authentication (Pairing Code & QR Code)

• Pairing Code Verification: Connect without camera scanning using an 8-character code.
• QR Code Scan: Standard QR code scanner in terminal.

Interactive Multi-Tier Catalog

• Interactive Category List: Browse travel categories via InteractiveEngine buttons.
• Product Carousel Cards: Scrollable visual product cards with titles, descriptions, pricing, and action buttons.
• Product Detail & Ordering: Full package breakdown with direct order action triggers.

RAG-Powered AI Engine

• Retrieval-Augmented Generation: Matches incoming user inquiries against db/knowledge.json and catalog data using keyword and relevance scoring.
• Multi-Tier Model Pipeline:
  • Groq Primary Models: openai/gpt-oss-120b, llama-3.3-70b-versatile, openai/gpt-oss-20b (Vision: qwen/qwen3.6-27b).
  • OpenRouter Fallback: meta-llama/llama-3.3-70b-instruct (Vision: meta-llama/llama-3.2-11b-vision-instruct).
• Configurable CS Persona: Generates context-grounded responses according to predefined business policies.

Post-Order Cooldown System

• Automated Silent Period: When a customer clicks order, the bot sends an acknowledgment message and enters a configurable cooldown period (default: 6 hours).
• Admin Isolation: During active cooldown, the bot ignores further messages from that customer so human administrators can handle follow-ups directly.
• Custom Overrides: Administrators can set custom durations using .jeda-<minutes>-<number> or lift cooldowns via .uncooldown <number>.

Call Handling & Privacy

• Automatic Call Rejection: Rejects incoming voice and video calls to maintain connection stability.
• No Auto-Read for Groups and Channels: Preserves read receipts and prevents automated group/status reading.
• LID Resolution: Maps WhatsApp Linked IDs (@lid) to standard phone number formats.

---

Command Reference

Customer Commands

Command	Description
.katalog	Displays interactive category selection and travel packages
.help	Escalates conversation to human customer service administrators

Admin / Owner Commands

Command	Description
.menu	Displays complete management menu based on caller role
.mode	Views current operation mode and mode switcher options
.public	Enables public mode (responds in both private and group chats)
.withoutgroup	Enables private-only mode (ignores group chats)
.self	Enables self-only mode (responds only to the bot number)
.myadd-mode	Enables whitelist-only mode
.myadd <number>	Adds a phone number to the whitelist
.myadd-del <number>	Removes a phone number from the whitelist
.myadd-list	Displays current whitelisted numbers
.after-co	Manages post-order cooldown settings and durations
.jeda-<minutes>-<number>	Sets custom cooldown duration for a specific phone number
.uncooldown <number>	Clears cooldown state for a phone number immediately
.latih-ulang	Reloads knowledge.json and catalog data into memory cache
.owner-co	Manages owner list configuration

---

Troubleshooting

1. Error: Cannot find package 'dotenv' or ERR_MODULE_NOT_FOUND

Cause: Dependencies are not yet installed in the project folder.
Solution: Run the following command in the project directory:

npm install

---

2. Bot Does Not Reply to a Customer After Order

Cause: The customer number is in the 6-hour Cooldown Period to allow human administrators to follow up without bot interference.
Solution: To reset cooldown manually, the owner can send:

.uncooldown 62812xxxxxxxx

---

3. Resetting WhatsApp Session or Changing Numbers

Solution: Stop the bot (Ctrl + C), delete the auth_session directory, and run npm start to generate a new pairing code or QR code.

---

Directory Structure

cerya/
├── .env                  # Environment variables (API keys)
├── .env.example          # Environment template
├── .gitignore            # Git exclusion rules
├── package.json          # Project manifest and dependencies
├── index.js              # Application entry point
├── config.js             # Central bot configuration and owner number
├── assets/
│   └── banner/           # Visual banner assets
├── db/
│   ├── config.json       # Runtime configuration (mode, cooldown, flags)
│   ├── owners.json       # Registered owner numbers
│   ├── myadd.json        # Whitelisted numbers
│   ├── lid-map.json      # WhatsApp LID to phone number mapping
│   ├── cooldown.json     # Active cooldown records
│   ├── sessions.json     # Chat history memory
│   ├── knowledge.json    # Knowledge base for RAG retrieval
│   └── katalog/
│       ├── categories.json # Product categories
│       └── products.json   # Product and package records
└── src/
    ├── index.js          # Subsystem initialization and lifecycle
    ├── connection.js     # WhatsApp socket manager and pairing handler
    ├── handler.js        # Main message handler and RAG router
    ├── db.js             # Atomic JSON file reader and writer
    ├── engine/
    │   ├── ragSearch.js  # RAG keyword relevance scoring engine
    │   ├── promptBuilder.js # System prompt constructor
    │   ├── aiClient.js   # Groq and OpenRouter API client
    │   └── typingSimulator.js # Typing state simulator
    ├── katalog/
    │   ├── katalogFlow.js # Interactive carousel and catalog builder
    │   └── cooldownManager.js # Cooldown state manager
    ├── router/
    │   ├── roleGuard.js  # Role verification (Owner, Trusted, Customer)
    │   └── commandRouter.js # Prefix command dispatcher
    ├── commands/         # Command handlers (.menu, .mode, etc.)
    └── lib/              # Utilities (logger, lid, socket, exif, asset-manager)

---

CERYA WA BOT • Developed by ricnah