WhatsAgentAI v1.0

Welcome to the official documentation for WhatsAgentAI — the most powerful AI-driven WhatsApp SaaS platform. Empower your business with autonomous agents that sell, support, and scale your operations 24/7.

✨ Key Features

📦 Core Components

📋 Requirements

Ensure your server meets these minimum requirements for a stable production environment.

⚡ Easy Installation (Ubuntu VPS)

WhatsAgentAI includes automated scripts to install and deploy the platform on a fresh Ubuntu VPS.

🖥️ Requirements

• Ubuntu 22.04 LTS (recommended)
• Minimum 2GB RAM
• Root access
• Domain names (required for SSL setup)

Step 1 — Complete Installation

1. Upload the project files to your VPS.
2. SSH into your server:

   ssh root@your-server-ip

3. Navigate to the setup directory:

   cd Projects/setup

4. Run the installer:

   sudo bash setup.sh


5. Select: 1) Complete Installation

The script will automatically:

• ✅ Install Node.js, MongoDB, Docker, and PM2
• ✅ Deploy Evolution API
• ✅ Configure backend & frontend environment
• ✅ Build the frontend
• ✅ Start the application

After completion, the platform will be running on your server.

Step 2 — Deploy with Domain & SSL

Point your Frontend and Backend domains (A records) to your VPS IP. Then run:

sudo bash deploy.sh

The script will:

• ✅ Configure Nginx reverse proxy
• ✅ Enable HTTPS using Let’s Encrypt
• ✅ Update environment URLs
• ✅ Restart the application

Your platform will then be live on your domain.

🔧 Manual Setup & Environment

If you prefer a manual setup or are working in a custom environment, follow the steps below to configure your system.

1. System Prerequisites

Before proceeding, ensure your server has the following services installed and running:

• Node.js: v20.x or later
• MongoDB: v6.0 or later (running locally or via Atlas)
• Docker: Required for running the Evolution API engine
• PM2: To manage background processes (npm install -g pm2)

2. Backend Configuration (.env)

Navigate to Projects/backend and create a .env file. Below is a detailed breakdown of the required variables:

Note: Ensure NODE_ENV=production is set in production environments for optimized performance.

3. Frontend Configuration (.env)

Navigate to Projects/frontend and create a .env file:

# Point this to your Backend API URL (with /api suffix)
NEXT_PUBLIC_API_URL=https://api.yourdomain.com/api

4. Starting the Application

Once your environment variables are set, run the following commands in order:

For Backend:

cd Projects/backend
npm install
pm2 start server.js --name whatsagent-api

For Frontend:

cd Projects/frontend
npm install
npm run build
pm2 start npm --name whatsagent-ui -- start

Verification: Run pm2 status to ensure both processes are online.

🔐 Google OAuth Setup

Required for secure user login and registration.

1. Create a new project in Google Cloud Console.

2. Enable OAuth Consent Screen.
3. Create OAuth 2.0 Client IDs (Web Application).

4. Add Authorized Redirect URI: [BASE_URL]/api/auth/google/callback.
5. Copy Client ID and Secret to your backend .env file.

📱 Evolution API Configuration

The Evolution API is the high-performance engine that connects WhatsAgentAI to the WhatsApp network. It runs as a containerized stack on your VPS.

1. Deployment Overview

The automated setup.sh script deploys the following services via Docker Compose:

• evolution_api: The core API service (Port 8080).
• evolution_postgres: Database for storing instance and message data.
• evolution_redis: Cache layer for high-speed performance.

2. Critical Security Keys

🛠️ Evolution API Recovery & Fix

If you encounter connection issues or the QR code fails to load, you can use the built-in repair tool in the setup script:

1. Navigate to Projects/setup.
2. Run sudo bash setup.sh.
3. Select Option 3: Fix Evolution API (reinstall / restart).

This will recreate the environment files and restart the Docker containers without affecting your main application data.

🧠 OpenRouter Setup (LLM)

OpenRouter is used to access advanced Large Language Models (like GPT-4 or Claude 3) that drive the conversation logic and message analysis.

1. Generate your API Key at openrouter.ai/settings/keys.
2. Login to your platform as Admin and go to Admin > AI Provider.
3. Paste your key into the API Key field and click Save.

👑 Admin Panel Guide

The Admin Panel is the control center for your SaaS. Use it to oversee the entire platform, manage user accounts, and configure the business logic.

1. User Management (Root)

View and manage all registered accounts on your platform.

• Search & Filter: Find users quickly by name or email.
• Add New User: Manually create accounts and assign roles (Admin or Member) and a subscription plan.
• Status Control: Instantly Activate or Deactivate any user account to grant or revoke access.
• Plan Override: Manually change a user's subscription tier using the "Change Plan" dropdown.

2. Plans & Resource Limits (`/admin/plans`)

Define the subscription structure and platform limits.

• Free Trial Limits: Set global thresholds (Agents, Leads, Campaigns) for users who haven't purchased a plan yet.
• Subscription Builder: Create tiers with custom naming, pricing, and billing intervals (Monthly, Yearly, or One-time).
• Dodo Payments Link: Input the Dodo Product ID to sync your local plans with the payment provider.

3. Payment Gateways (`/admin/gateways`)

Enable and configure the supported payment stack.

• Stripe, PayPal, Razorpay, & Dodo: Enter your API keys and secrets for each provider.
• Sandbox Mode: Toggle individual gateways between "Test Mode" and "Live" for safe transaction testing.
• Instant Deployment: Changes to gateway status reflect immediately on the user-side upgrade page.

4. Purchase History (`/admin/purchases`)

A centralized ledger of every transaction occurring on the platform.

• Transaction Tracking: Monitor payment statuses (Completed, Pending, or Failed).
• Financial Logs: View exactly who paid, how much, and which gateway was used.
• Export CSV: Download your entire transaction history for accounting and reporting purposes.

5. Global Analytics (`/admin/analytics`)

Gain insights into your platform's growth trajectory.

• Growth Metrics: View percentage growth for users, revenue, and active plans.
• Performance Charts: Analyze a 7-day rolling chart of revenue and new user signups.
• Platform Stats: Monitor the total number of active subscriptions and generated revenue.

6. Admin Settings (`/admin/settings`)

The master configuration for your platform's basic identity.

• Global Currency: Select the default currency (USD, EUR, INR, etc.) for the entire SaaS.
• Support Email: Define the official contact address that users see for help and account issues.

👥 User Roles

💳 Payment Gateways Setup

WhatsAgentAI v1 supports 4 major payment providers. You can enable any combination of them.

Go to Admin Panel > Payment Gateways to configure these.

Stripe

1. Go to Stripe Developer Dashboard.
2. Copy your Publishable Key (pk_...) and Secret Key (sk_...).
3. Paste them into the Stripe section in the Admin Panel.
4. Toggle Enabled to On.

PayPal

1. Go to PayPal Developer Dashboard.
2. Create a new App. Copy the Client ID and Secret Key.
3. Paste them into the PayPal section in the Admin Panel.
4. Toggle Enabled to On.
5. For testing, refer to the PayPal Sandbox Guide.

Razorpay

1. Go to Razorpay Dashboard.
2. Generate a new Key. Copy Key ID and Key Secret.
3. Paste them into the Razorpay section in the Admin Panel.

Dodo Payments

1. Go to Dodo Payments Dashboard.
2. Copy your API Key.
3. If you are using Product IDs for plans, ensure the Dodo Product ID field in your Plan config matches the product ID in Dodo.
4. Webhook Setup (Important):
• Go to Dodo Developer Webhooks.
• Add a new Webhook Endpoint: [BASE_URL]/api/payments/dodopayments/webhook.
• Local Testing: Ensure you have ngrok configured to get a public URL for your local server.

📊 User Plans & Billing

When a user upgrades their plan:

1. They select a plan in their settings.
2. Payment is processed through your configured gateway.
3. Upon success, the Webhook triggers and instantly updates their resource limits.

🚀 Quick Demo Guide (See the Magic)

Follow this checklist to see WhatsAgent AI in action in less than 5 minutes.

📲 WhatsApp Instances

Before using AI or Campaigns, you must connect a WhatsApp account. This is the first step when you onboard for the first time.

1. Initial Prompt: On the Dashboard, you will see a "Connect WhatsApp to get started" message. Click the Connect WhatsApp button.


2. Create Instance: Click on + Create Your First Instance.


3. Launch: In the modal, enter a friendly name for your instance (e.g., "Customer Support HQ") and click Launch Instance.


4. Settings: You will be taken to the Settings page. Here, click the Connect WhatsApp button within your new instance card.


5. Pairing: A QR Code will appear on the screen. On your phone, open WhatsApp and go to Settings > Linked Devices > Link a Device to scan it.


6. Success: Once scanned, your status will instantly change to Connected and you are ready to deploy AI Agents!

🤖 Creating AI Agents

Create an AI agent for campaigns and auto-reply. Go to Agents > Create Agent and fill in the form as below.

Basic Information

Name, instance, and availability.

• WhatsApp Instance: Select the WhatsApp instance this agent will use (e.g. Demo WhatsApp).
• Agent Name: Enter a name (e.g. Sales Bot, Support Assistant).
• Description: Describe what this agent is for.
• Use for Auto-Reply & Campaigns: Enabled by default. Lets this agent reply to chats and write campaign messages.
• Handle incoming messages: Optional switch. Only one agent per instance can have this enabled. When on, this agent will reply to incoming WhatsApp messages based on the scope you set.
• Welcome Message (optional): A message sent before the AI takes over—useful as a first-time user message.

AI Configuration

Model and system prompt.

• AI Model: Select an OpenRouter model for replies. Gemini 3 Flash Preview is recommended. You can see model details, pricing, and more at https://openrouter.ai/models.
• System Prompt: Define the agent’s role, rules, and personality (e.g. “You are a helpful assistant for my business…”).

Knowledge Base

Include selected knowledge in the agent prompt for better answers. All of the following are configured in the Knowledge Base page.

• Include business context: Option to include business name, description, services, hours, and location from your knowledge base.
• Include FAQs: Option to include FAQs you’ve added in the knowledge base.
• Use tools: Option to let the agent use tools (e.g. file assets) that you’ve configured in the knowledge base page.

When you’re done, click Create agent to save.

👥 Leads & CRM

Leads are the people you message in campaigns. You manage them on the Leads page and can import from WhatsApp Contacts. Leads are scoped per WhatsApp instance.

Leads page

Go to Leads in the sidebar. The table shows name, phone/source, created date, status, and actions.

• Add Lead: Click Add Lead to create a lead manually. Enter Name (optional), Phone (required), and Source (e.g. Manual Add, Campaign). The lead is added for the currently selected instance.
• WhatsApp Contacts: Click WhatsApp Contacts to open the contacts page. There you can see everyone from your connected WhatsApp account and add them to Leads with one click (see below).
• Upload CSV: Use Upload CSV to import many leads at once. Your CSV must have a phone column; a name column is optional. Other columns are ignored. Select an instance in the header first.
• Search and filter: Use the search box to find leads by name or phone. Use the status dropdown to filter by All statuses, New Lead, Contacted, or Closed (Won).
• Status: Change a lead’s status with the dropdown in the table: New Lead, Contacted, or Closed (Won).
• Edit / Delete: Use the edit (pencil) and delete (trash) actions on each row to update name, phone, and source or remove the lead.
• Run Campaign: From the Leads page you can open the Run Campaign flow: choose campaign name, WhatsApp instance, AI agent, and select which leads to target; then click Create campaign. Start the campaign from the Campaigns page.

WhatsApp Contacts page

Go to Leads then click WhatsApp Contacts, or open Contacts from the menu. Your WhatsApp instance must be connected.

• View: You see all contacts from the selected WhatsApp account (name, phone/ID, profile picture). Groups are excluded from the list.
• Search and filter: Search by name or phone. Filter by All contacts, In Leads (only contacts already in your Leads list), or Not in Leads (contacts you haven’t added yet).
• Add to Leads: For any contact not yet a lead, click Add to Leads to add them to your Leads list for that instance in one click. Contacts already in Leads show “Already in Leads.”

Syncing: Names and profile pictures are synced from WhatsApp in the background on the Leads and Contacts pages, so your lead list stays up to date with WhatsApp.

📅 Creating Campaigns

Broadcast messages to your leads. Create a campaign, choose recipients, then start it from the Campaigns page. The campaign uses the WhatsApp instance selected in the header.

Create a new campaign

1. Go to Campaigns in the sidebar and click + New Campaign.
2. Campaign name: Enter a name (e.g. Welcome campaign).
3. WhatsApp instance: Shown read-only; it is the instance currently selected in the header. Change the instance in the header first if you need a different one.
4. Message *: Enter the message to send to leads (required).
5. Attach file (optional): You can attach an image or PDF. When you attach a file, a Send message as caption option appears—when checked (default), the message is sent as the caption of the image or document.
6. Recipients (Leads): Click Load leads to fetch leads for the instance in the header. Then select which leads to include using the checkboxes. Use All / None to select or clear all. You must select at least one lead.
7. Click Create campaign. The campaign is created in a scheduled (or pending) state.

Start and monitor

• Start: On the Campaigns list, click the green Start button on a campaign card to begin sending. You can also open the campaign and click Start there.
• Campaign cards: Each card shows the campaign name, date, status (e.g. scheduled, running, completed), a progress bar, and counts: sent, failed, Total. Click a card to open the campaign detail page.
• Campaign detail: The detail page has an Overview tab (total recipients, sent, failed, progress %, and a message preview showing how the broadcast looks in WhatsApp) and a Recipients tab (per-contact status: pending, sent, or failed, with optional error details). Use Refresh to update; the page auto-refreshes while a campaign is running.

💬 Inbox & Messaging

The Inbox is your unified view of WhatsApp conversations for the instance selected in the header. You can read and reply to chats, toggle AI auto-reply per conversation, and update lead status without leaving the Inbox.

Chat list (left panel)

• Search: Use Search or start a new chat to filter conversations by contact name or WhatsApp number.
• Conversations: Chats are listed by most recent activity. Each row shows the contact’s avatar, name, an AI Active or AI Paused badge, the time of the last message, and a preview of the last message. An unread count badge appears when there are unread messages.
• If the list is empty, run a campaign or wait for incoming messages to start conversations.

Conversation view (right panel)

Select a chat to open it. The header shows the contact name, WhatsApp ID, and two controls:

• Auto-reply (toggle): Turn AI Active on to let your AI agent reply to this contact, or off (AI Paused) to handle the chat yourself. You can change this at any time.
• Lead status: When the conversation is linked to a lead, a dropdown lets you set or change the lead status: New Lead, Contacted, or Closed (Won). Leads are created automatically for new conversations when possible.

Messages and replies

• Message history: Incoming messages appear on the left; your (or the agent’s) replies on the right. The app supports text, images, and documents—including images or PDFs sent by the AI from your Knowledge Base tools (e.g. menus, brochures) and campaign media.
• Manual takeover: Type in the Type a message field and send. Your reply is sent via WhatsApp and the AI is automatically paused for this chat so you take over the conversation. You can turn Auto-reply back on when you’re done.

Instance

Conversations are shown for the WhatsApp instance currently selected in the top header. Switch the instance there to see and reply to chats for another connected account.

📚 Knowledge Base & Tools

The Knowledge Base holds business context, FAQs, and tools (files) for your agents. Go to Knowledge Base in the sidebar. The page uses the WhatsApp instance selected in the header—select an instance first. Click Save after editing Business or FAQs.

Business & FAQs tab

Two cards side by side:

• Business context: Information your AI agents use to answer customer questions. Fill in Business name, Description (what your business does), Services / products (comma-separated), Working hours, and Location.
• FAQs: Common questions and answers for agents to use. Click + Add to add an entry; each has a Question and Answer field. Remove an FAQ with the trash icon. Use these for things like “Do you have a menu?”, “What are your opening hours?”, or “Do you offer refunds?”

Tools tab

Tools let the AI send files (images, PDFs, documents) when it decides to use a tool. The AI uses each tool’s description to know when to trigger it.

• Create New Tool: Click + Create New Tool. In the modal:
  • Function Name (Internal): Unique identifier using letters, numbers, and underscores (e.g. send_brochure, send_menu).
  • File Type: Choose Image, PDF, or Document (Word, etc.).
  • Description (Prompt Trigger) *: Required. Describe when the AI should use this tool (e.g. “Sends the brochure when the user asks for more info or pricing”). The AI reads this to decide when to send the file.
  • Upload File: Attach the image, PDF, or document.
  • Caption (Optional): Message sent with the file (e.g. “Here’s our brochure—reach out if you have questions.”).
  Then click Create Tool.
• Tool list: Each tool shows a preview, its function name, file type, and description. Use the View (eye) and Download icons to open or download the file; use the Delete (trash) icon to remove the tool.

When an agent has “Use tools” enabled in its Knowledge Base options, it can call these tools during chats—for example sending the menu when a customer asks for it, or the brochure when they ask for more info.

❓ Troubleshooting

Common issues, error messages, and how to resolve them. Many errors come from the backend when something is missing or over limit.

✉️ Support

For technical help and bug reports, please contact us via our official channels:

• Support Portal: envato.aqeelshamz.com
• Email: aqeelten@gmail.com