Complete User Guide

Everything you need to set up, configure, and run AI-powered WhatsApp customer support for your business.

WhatsApp AI

GPT-4o

RAG Knowledge Base

Multi-tenant

Platform Overview

WA Support AI is a multi-tenant SaaS platform that lets e-commerce and service businesses automate WhatsApp customer support using AI. Each business (company) has its own isolated workspace — conversations, customers, knowledge base, and settings are never shared between companies.

End-to-End Message Flow

Customer sends WhatsApp message

→ Meta sends webhook → POST /api/webhooks/whatsapp

→ Message stored · QueueJob created

→ Cron fires every 60s → /api/queue/process

→ Check subscription quota

→ Check escalation keywords → notify agent if triggered

→ Search knowledge base (RAG) → inject matching content

→ Build last-20-message history

→ Call OpenAI GPT-4o

→ Send AI reply via WhatsApp Cloud API

→ Store reply · Increment usage counters

User Roles & Permissions

Every user belongs to a company and has one of these roles:

Permission	Company Admin	Support Agent
View dashboard, conversations, analytics	✅	✅
Reply to conversations	✅	✅
Toggle AI per conversation	✅	✅
Close / change conversation status	✅	✅
View customer profiles	✅	✅
Edit customer notes & lifecycle stage	✅	—
Configure WhatsApp credentials	✅	—
Configure AI settings & prompt	✅	—
Upload knowledge base documents	✅	—
View audit log	✅	—
Edit company settings	✅	—
Invite team members	✅	—
View billing & subscription	✅	—

Getting Started

Create your account

Go to the home page and click Get started free. Fill in your company name, your name, email, and a password. You'll be logged in automatically as Company Admin.

Connect WhatsApp

Go to Dashboard → WhatsApp and enter your Meta credentials (Phone Number ID + Access Token). Then configure the webhook in the Meta Developer Portal.

See the WhatsApp Setup section below for step-by-step instructions.

Configure AI

Go to Dashboard → AI Settings. Write a system prompt that describes your business and how the AI should behave. Set your escalation keywords.

Upload your knowledge base

Go to Dashboard → Knowledge Base. Upload your FAQ, product catalog, or policy documents as .txt, .md, .csv, or .pdf files (max 10 MB each).

Invite your team

Go to Dashboard → Settings → Invite Team Member. Enter an email, choose a role, and share the generated invite link.

Go live

Send a WhatsApp message to your connected number. Within 60 seconds the AI will reply. Monitor conversations in Dashboard → Conversations.

WhatsApp Setup — Step by Step

You need a Meta Developer account and a WhatsApp Business Account before starting.

Create a Meta App

Go to developers.facebook.com → My Apps → Create App. Choose Business type. Add the WhatsApp product to your app.

Get your credentials

In WhatsApp → API Setup, find:

Phone Number ID (shown under "From" phone number)

Access Token (use a System User permanent token for production)

App Secret (Meta App → Settings → Basic)

Enter credentials in dashboard

Go to Dashboard → WhatsApp. Enter Phone Number ID and Access Token. Save.

Configure the webhook

In Meta Developer Portal → WhatsApp → Configuration → Webhook:

Callback URL: https://your-domain.com/api/webhooks/whatsapp

Verify Token: any string you choose (e.g. mysecret123)

Subscribe to the messages webhook field

Enter verify token in dashboard

Back in Dashboard → WhatsApp, enter the same Verify Token you used in Meta Portal.

Test the connection

Click Test Connection in the dashboard. A green "Connected" badge confirms everything is working.

Development tip: Use ngrok to expose localhost to the internet so Meta can reach your webhook during development: ngrok http 3000

AI Configuration

Field	Description	Default
AI Enabled	Master switch — turns off AI for all conversations when disabled	On
Model	OpenAI model to use for replies	gpt-4o
System Prompt	Instructions that define the AI's persona, scope, and tone	Generic assistant
Temperature	0.0 = precise/factual · 1.0 = creative/varied	0.7
Max Tokens	Maximum length of each AI reply	500
Escalation Keywords	Words that trigger human handoff (comma-separated, case-insensitive)	refund, manager, human, lawsuit, angry

Example system prompt:

You are a friendly customer support agent for Acme Electronics.
Help customers with orders, returns, and product questions.
Be concise and professional. If unsure, say so honestly.
Do not discuss competitors or make promises about delivery times.

Tip: Keep the system prompt under 500 words. The more specific and focused it is, the better the AI performs.

Knowledge Base

Upload documents that the AI uses to answer customer questions. Documents are automatically chunked into ~500-word pieces. When a customer message arrives, the top 3 matching chunks are injected into the AI's context.

Format	Extension	Best for
Plain text	.txt	FAQs, policies, general info
Markdown	.md	Formatted docs, product guides
CSV	.csv	Product catalogs, pricing tables
PDF	.pdf	Brochures, manuals (text extraction only)

Best practices:

Write FAQs as Q: ... A: ... format for best matching

Keep one topic per file — the AI retrieves by relevance, not by document

Avoid PDFs with images or complex layouts — only raw text is extracted

Use clear, customer-facing language (the AI mirrors your writing style)

Maximum file size: 10 MB per upload

Uploading: Go to Dashboard → Knowledge Base → drag and drop your file onto the upload zone, or click to select. The status changes to Active once processing is complete (usually a few seconds).

Conversations

Every WhatsApp conversation with a customer appears in the Conversations inbox.

OPENNew, unassigned

ACTIVEAI is responding

PENDINGWaiting for customer

ESCALATEDNeeds human agent

RESOLVEDIssue solved

CLOSEDNo further action

Inside a conversation you can:

Read the full message thread (customer left, AI/agent right)

Toggle AI on or off for just this conversation

Change the conversation status using the status selector

Send a manual reply — it's delivered to the customer via WhatsApp immediately

The thread auto-refreshes every 5 seconds (stops when CLOSED)

Use the search bar to find conversations by customer name or phone number. Use the status filter to show only ESCALATED conversations that need attention.

Customers

Customers are automatically created the first time they send a WhatsApp message. Their phone number is the unique identifier.

View profile: name, phone, email, lifecycle stage

See stats: total conversations, first seen, last active

Add notes about the customer

Set lifecycle stage: LEAD, PROSPECT, CUSTOMER, CHURNED, VIP

Browse full conversation history for the customer

Lifecycle Stage	Meaning
LEAD	First contact, not yet a buyer
PROSPECT	Interested, evaluation stage
CUSTOMER	Has made a purchase
VIP	High-value or loyal customer
CHURNED	Was a customer, no longer active

Analytics

Messages per Day (Bar Chart)

Last 7 days. Stacked bars show customer messages vs. AI replies. A high AI ratio means the AI is handling most support.

Conversation Status (Donut Chart)

Live breakdown of all conversations by status. A large ESCALATED slice means your escalation keywords may be too broad, or human agents are needed.

Notifications & Escalations

Notifications appear in Dashboard → Notifications. The most important type is ESCALATION — created automatically when a customer message contains an escalation keyword.

Type	When created
ESCALATION	Customer message matches an escalation keyword
SYSTEM	Platform events (invites, system messages)
AI_FAILURE	AI processing failed for a message
BILLING	Quota warnings

Handling an escalation:

See the notification

Check Dashboard → Notifications for the escalation alert.

Open the conversation

Click through to the conversation. The AI has already sent a handoff message.

Reply as an agent

Type your response in the agent reply box and send.

Resolve

Change status to RESOLVED when the customer's issue is handled.

Adjust your Escalation Keywords in AI Settings to reduce false positives. Too many escalations means the AI isn't handling enough; too few means frustrated customers aren't reaching a human.

Settings & Team Management

Company Profile

Edit company name, contact email, and timezone

Slug (e.g. acme-corp) is set at registration and cannot be changed

Billing & Usage

View current plan (FREE / TRIAL / PRO)

Messages used vs. limit this period (progress bar)

AI tokens used vs. limit this period (progress bar)

When the limit is reached, AI auto-replies pause — manual replies always work

Inviting Team Members

Go to Settings → Invite Team Member

Enter their email, name (optional), and role

Click "Generate Invite Link"

The link is valid for 7 days.

Share the link

The invitee opens it and registers with their own password.

Audit Log

Every significant action in your workspace is automatically recorded in the Audit Log at Dashboard → Audit Log. Entries cannot be edited or deleted.

Action	Triggered when
company_registered	New account created
settings_updated	Company profile saved
ai_settings_updated	AI configuration changed
document_uploaded	Knowledge base file processed
user_invited	Invite link generated
conversation_escalated	Escalation keyword matched
conversation_closed	Conversation marked closed/resolved
message_sent	Agent sent a manual reply

The dashboard shows the last 100 entries. All entries are stored in the database indefinitely.

How the AI Works

1 System Prompt

Your instructions to the AI — who it is, what it can answer, and how it should respond. Set in AI Settings.

2 Knowledge Base (RAG)

Top 3 document chunks that match the customer's keywords are injected between the system prompt and conversation history, giving the AI factual grounding.

3 Conversation History

The last 20 messages are included so the AI remembers what was already discussed and doesn't repeat itself.

4 Escalation Check

Before calling OpenAI, the platform checks the message for escalation keywords. If found, it skips AI and routes to a human agent.

Troubleshooting

AI is not replying to messages

Check: WhatsApp connected? · AI Enabled toggle ON? · Conversation AI toggle ON? · Subscription quota not exceeded? · Queue running? (visit /api/queue/process in dev)

Stop the dev server, delete the .next folder, restart with npm run dev. A stale Turbopack cache can serve old middleware.

Service worker errors in browser console

Open DevTools → Application → Service Workers → Unregister all. Or open an Incognito window.

Knowledge base not being used by AI

Verify the document status is 'Active' in the Knowledge Base page. Try more direct keywords in test messages.

Webhook verification failing

Make sure the Verify Token in the dashboard exactly matches the one entered in Meta Developer Portal (case-sensitive).

Escalation triggered too often

Review your Escalation Keywords list in AI Settings. Remove overly broad words and add more specific phrases.

Ready to get started?

Set up your AI WhatsApp support in minutes.