Getting Started

Platform Overview

This WhatsApp Marketing Platform is a comprehensive SaaS solution that enables businesses to leverage the WhatsApp Business API for marketing, customer support, and engagement. The platform provides a complete suite of tools for managing WhatsApp communications at scale.

Key capabilities include:

• Multi-Channel Management — Connect and manage multiple WhatsApp Business Accounts
• Campaign Management — Send bulk messages with templates, scheduling, and targeting
• Unified Inbox — Real-time conversations with assignment and status tracking
• Automation Flows — Visual flow builder for automated message sequences
• AI-Powered Auto-Reply — Intelligent responses using OpenAI/custom AI with knowledge base
• Chat Widget — Embeddable website chat widget with lead capture
• Template Management — Create, submit, and manage WhatsApp message templates
• Analytics & Reports — Comprehensive dashboards and exportable reports
• Team Collaboration — Multi-user access with role-based permissions
• Subscription Plans — Configurable plans with Stripe/Razorpay payment integration
• REST API — Programmatic access for external integrations
• Notification System — In-app, email, and sound notifications

System Requirements

To deploy this platform, you'll need the following:

Server Requirements

• Ubuntu 20.04+ or Debian 11+ (recommended)
• Minimum 2 vCPUs, 4 GB RAM (4 vCPUs, 8 GB recommended)
• 20 GB SSD storage minimum
• Root or sudo access

Software Requirements

• Node.js 20.x LTS
• PostgreSQL 14+ (or managed database like Neon, Supabase, AWS RDS)
• Nginx (reverse proxy)
• PM2 (process manager)
• Git
• Certbot (SSL certificates)

External Accounts

• Meta Developer Account
• Meta Business Account (verified)
• Domain name with DNS access
• SMTP email service (for notifications)
• Stripe or Razorpay account (for payments, optional)
• OpenAI API key (for AI features, optional)

Architecture Overview

The platform follows a modern full-stack architecture:

• Frontend: React 18 + TypeScript + Vite + TailwindCSS + shadcn/ui
• Backend: Node.js + Express + TypeScript
• Database: PostgreSQL with Drizzle ORM
• Real-time: Socket.IO for live messaging and notifications
• File Storage: Local uploads or DigitalOcean Spaces / S3

Installation Guide

VPS Server Setup

Start by provisioning a VPS from any provider (DigitalOcean, AWS, Hetzner, Vultr, etc.) running Ubuntu 22.04 LTS.

ssh root@your-server-ip

apt update && apt upgrade -y

adduser chatlix
usermod -aG sudo chatlix
su - chatlix

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node --version
npm --version

sudo apt install -y git build-essential curl wget unzip

Domain & SSL Setup

Type: A
Name: @ (or your subdomain, e.g., app)
Value: YOUR_SERVER_IP
TTL: 3600

sudo apt install -y certbot python3-certbot-nginx

sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

Database Setup

You can use a local PostgreSQL instance or a managed database service.

Option A: Local PostgreSQL

sudo apt install -y postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database and user
sudo -u postgres psql
CREATE USER chatlix WITH PASSWORD 'your_secure_password';
CREATE DATABASE chatlix_db OWNER chatlix;
GRANT ALL PRIVILEGES ON DATABASE chatlix_db TO chatlix;
\q

Option B: Managed Database (Recommended for production)

Use services like Neon, Supabase, AWS RDS, or DigitalOcean Managed Databases. Copy the connection string provided by the service.

DATABASE_URL=postgresql://user:password@host:5432/database?sslmode=require

Application Installation

cd /home/chatlix
git clone https://your-repo-url.git chatlix-platform
cd chatlix-platform

npm install

cp .env.example .env
nano .env

npm run db:push

npm run seed

npm run build

npm start

First-Run Setup & Superadmin Login

After completing the server setup, database migration, and starting the application for the first time, you need to perform the initial platform configuration. Here's what happens and what to do:

Step 1: Access the Platform

Open your browser and navigate to your configured domain (e.g., https://yourdomain.com). You will see the platform's public homepage with the login option.

Step 2: Login with Default Superadmin Credentials

The npm run seed command creates the default Superadmin account along with all essential platform data. Use the following default credentials to log in:

Username: admin
Password: Admin@123

Step 3: Configure Brand Settings

Navigate to Settings > Brand Settings to personalize your platform:

• Application Name — Set your platform's display name (shown in header, emails, browser title)
• Tagline — A short description for your platform
• Logo & Favicon — Upload your brand logo and favicon
• Color Theme — Customize the primary/accent colors
• Homepage Content — Edit hero text, features, stats shown on the public landing page

Step 4: Configure Meta / WhatsApp API

Go to Settings > Embedded Signup and enter your Meta App credentials:

• Meta App ID — From your Meta App Dashboard > App Settings > Basic
• Meta App Secret — From the same page (keep this secret!)
• Embedded Signup Config ID — From WhatsApp > Embedded Signup in Meta App Dashboard

Also set the Webhook Verify Token (any random string) and configure the webhook URL in Meta. See the Webhook Configuration section for details.

Step 5: Set Up Email / SMTP

Navigate to Settings > Email (or set via environment variables) to configure email notifications:

• SMTP Host — e.g., smtp.gmail.com, smtp.sendgrid.net
• SMTP Port — Usually 587 (TLS) or 465 (SSL)
• SMTP User & Password — Your email account credentials or API key
• From Address — The sender address for outgoing emails

Step 6: Configure Payment Gateways (Optional)

If you want to sell subscription plans, go to Superadmin > Payment Providers to set up:

• Stripe — Enter your Stripe Secret Key and Publishable Key
• Razorpay — Enter your Razorpay Key ID and Key Secret
• Assign supported currencies to each provider

Step 7: Create Subscription Plans

Go to Superadmin > Plans to create your pricing tiers. Each plan defines:

• Plan name, description, and pricing (monthly/annual)
• Feature permissions (contacts limit, channels, automations, team members, etc.)
• Visual settings (icon, color, badge, popularity flag)

Step 8: Add Your First WhatsApp Channel

Now your platform is ready for use. You (or your clients) can add a WhatsApp channel via:

• Embedded Signup — Click "Add Channel" in Settings and follow the Facebook Login flow
• Manual Entry — Enter WABA ID, Phone Number ID, and Access Token directly

Environment Configuration

Create a .env file in the project root with these essential variables:

# Core
NODE_ENV=production
PORT=5000
SESSION_SECRET=your-random-secret-string-minimum-32-chars

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/chatlix_db

# Meta WhatsApp API
META_APP_ID=your_meta_app_id
META_APP_SECRET=your_meta_app_secret
WEBHOOK_VERIFY_TOKEN=your_custom_webhook_verify_token

# Email (SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your@email.com
SMTP_PASS=your_app_password
SMTP_FROM=noreply@yourdomain.com

# File uploads
UPLOAD_DIR=./public/uploads
MAX_FILE_SIZE=10485760

# Optional: Payment Gateways
STRIPE_SECRET_KEY=sk_live_xxxxx
STRIPE_PUBLISHABLE_KEY=pk_live_xxxxx
RAZORPAY_KEY_ID=rzp_live_xxxxx
RAZORPAY_KEY_SECRET=xxxxx

# Optional: AI
OPENAI_API_KEY=sk-xxxxx

Process Manager (PM2)

PM2 keeps your application running and automatically restarts it if it crashes.

sudo npm install -g pm2

pm2 start npm --name "chatlix" -- start
pm2 save
pm2 startup

pm2 status        # Check status
pm2 logs chatlix  # View logs
pm2 restart chatlix  # Restart
pm2 monit         # Monitor dashboard

Nginx Reverse Proxy

sudo apt install -y nginx

sudo nano /etc/nginx/sites-available/chatlix

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;

        # WebSocket support (for Socket.IO)
        proxy_read_timeout 86400;
    }

    client_max_body_size 50M;
}

sudo ln -s /etc/nginx/sites-available/chatlix /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Firewall Configuration

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo ufw status

Meta / WhatsApp Setup

Meta Developer Account

Create Meta App

📖 Meta Docs: Creating an App →

Add WhatsApp Product

📖 Meta Docs: Set Up Developer Assets →

Business Verification

To send messages to customers (not just test numbers), you need to verify your business with Meta. 📖 Meta Docs: Business Verification →

Phone Number Setup

You can use the test number provided by Meta or register your own business phone number. 📖 Meta Docs: Add a Phone Number →

Access Tokens

📖 Meta Docs: Access Tokens →

Temporary Token (for testing)

Generated in WhatsApp > API Setup. Valid for 24 hours.

Permanent Token (for production)

Webhook Configuration

Webhooks allow your platform to receive real-time events from WhatsApp (incoming messages, delivery status, etc.). How you configure webhooks depends on which channel connection mode you're using. 📖 Meta Docs: Set Up Webhooks →

Webhook Setup Steps (Common to Both Modes)

WEBHOOK_VERIFY_TOKEN=my-custom-verify-token-12345

Callback URL: https://yourdomain.com/api/webhooks/whatsapp
Verify Token: my-custom-verify-token-12345

Webhook Behavior: Embedded Signup vs. Manual Mode

Embedded Signup Setup

Embedded Signup lets your clients connect their WhatsApp Business Accounts directly through your platform without manually entering API credentials. This section covers the Meta App Dashboard configuration required by the superadmin. 📖 Meta Docs: Embedded Signup →

Required Meta Permissions

Before setting up Embedded Signup, ensure your Meta App has these permissions. For development/testing, these are available in test mode. For production, you must submit for App Review.

Meta App Dashboard Setup

https://yourdomain.com/

App Review & Permissions

For production use, your Meta App needs to go through Meta's App Review process to get the required permissions approved. In development/test mode, permissions work automatically for app admins and testers. 📖 Meta Docs: App Review →

Required Permissions

Steps for App Review

1. Go to App Review > Permissions and Features in your Meta App Dashboard
2. Request the required permissions listed above
3. Provide detailed descriptions and screencasts showing how each permission is used in your platform (see best practices →)
4. Submit for review (typically takes 3-7 business days)

Platform Modules

Dashboard

The Dashboard provides an at-a-glance overview of your WhatsApp marketing performance. It displays key metrics including total messages sent/received, active conversations, campaign performance, and contact growth over time.

• Message Statistics — Total sent, delivered, read, and failed messages
• Conversation Overview — Active, pending, and resolved conversation counts
• Campaign Performance — Recent campaigns with delivery rates
• Contact Growth — New contacts added over time
• Channel Health — Status of connected WhatsApp channels

Inbox & Conversations

The Inbox is a unified messaging interface for managing all WhatsApp conversations in real-time. It supports message assignment, status tracking, and multi-agent collaboration.

• Real-time messaging — Messages appear instantly via Socket.IO
• Conversation assignment — Assign conversations to specific team members
• Status management — Mark conversations as open, pending, or resolved
• Quick replies — Send pre-defined responses quickly
• Media support — Send and receive images, documents, audio, video, and locations
• 24-hour window — Automatic enforcement of WhatsApp's messaging window rules
• Template messages — Send approved templates outside the 24-hour window
• Contact info panel — View and edit contact details alongside conversations

Contacts Management

Manage your contact database with full CRUD operations, import/export, and segmentation.

• Add contacts — Individually or via bulk import (CSV/Excel)
• Contact profiles — Name, phone, email, tags, custom fields
• Groups — Organize contacts into groups for targeted campaigns
• Search & filter — Find contacts by name, phone, tags, or custom fields
• Export — Download contacts as CSV for external use
• Auto-creation — Contacts are automatically created when new numbers message you

Template Management

Create and manage WhatsApp message templates that comply with Meta's guidelines. Templates must be approved by Meta before use in campaigns or outside the 24-hour window.

• Template types — Marketing, utility, authentication templates
• Components — Header (text/image/video/document), body, footer, buttons
• Variables — Dynamic placeholders like {{1}}, {{2}} for personalization
• 60+ languages — Support for all WhatsApp-supported languages
• Status tracking — Monitor approval status (pending, approved, rejected)
• Draft system — Auto-save drafts before submitting for approval
• Preview — See how the template will appear on WhatsApp before submitting

Campaigns

Send bulk messages to targeted audiences using approved templates.

• Template-based — Select from approved templates with variable substitution
• Audience targeting — Send to contact groups, tags, or custom selections
• Scheduling — Schedule campaigns for optimal delivery times
• Throttling — Control sending speed to comply with API rate limits
• Real-time tracking — Monitor sent, delivered, read, and failed counts
• Campaign analytics — Detailed reports with delivery rates and engagement metrics
• A/B testing — Test different messages to optimize engagement

Automation Flows

Build visual automation workflows using the drag-and-drop flow builder. Automations trigger based on incoming messages and execute a series of actions.

Available Node Types

• Message Nodes — Text, image, video, document, list messages, location
• Logic Nodes — Conditions, delays, random split
• Action Nodes — Set variable, webhook call, HTTP request
• Contact Nodes — Add to group, update contact fields, tag contact
• Flow Control — Go to another flow, end flow

Automations support variable substitution using {{varName}} syntax in message fields.

Chatbot / Widget Builder

Create and customize embeddable chat widgets for your website. The widget captures leads and connects visitors to your team via real-time chat.

• Visual builder — Customize colors, position, welcome messages
• Lead capture form — Collect name, email, phone before chat starts
• AI-powered responses — Automatic AI replies using your knowledge base
• Conversation continuity — Returning visitors resume previous conversations
• Multi-site support — Create different widgets for different websites

Analytics & Reports

Comprehensive analytics covering all aspects of your WhatsApp marketing efforts.

• Message analytics — Delivery rates, read rates, response times
• Campaign reports — Per-campaign performance with charts
• Contact analytics — Growth trends, engagement scores
• Team performance — Response times and resolution rates per agent
• Exportable — Download reports in CSV format

Team Management

Invite and manage team members with role-based access control.

• Invite members — Send email invitations with predefined roles
• Role assignment — Assign Admin or Team roles with specific permissions
• Activity tracking — Monitor team member activities and performance
• Conversation assignment — Auto-assign or manually assign conversations to agents

Contact Groups

Organize contacts into groups for targeted messaging and campaign management.

• Create groups — Define groups with names and descriptions
• Add/remove contacts — Manage group membership individually or in bulk
• Campaign targeting — Select groups as campaign audiences

Bulk Import

Import large numbers of contacts from CSV or Excel files.

• CSV/Excel support — Upload files with contact data
• Column mapping — Map file columns to contact fields
• Duplicate handling — Skip, update, or create new on duplicates
• Progress tracking — Monitor import progress in real-time
• Error reporting — View details of any failed imports

AI & Auto-Reply

AI Overview

The platform includes an AI-powered auto-reply system that can respond to both WhatsApp messages and website widget chats. It uses your knowledge base to provide accurate, context-aware responses.

AI Provider Setup

Configure your AI provider in the channel settings or AI Assistant page:

• Provider — Select OpenAI or other supported providers
• Model — Choose the AI model (e.g., gpt-4o-mini, gpt-4o)
• API Key — Enter your provider's API key
• Temperature — Control response creativity (0 = focused, 1 = creative)
• Max Tokens — Set maximum response length
• System Prompt — Define the AI's personality and behavior

Knowledge Base

Train the AI with your business-specific information. The AI searches through training data and Q&A pairs to provide accurate, contextual responses.

• Training Data — Upload documents, FAQs, product info, policies
• Q&A Pairs — Define specific question-answer combinations
• Chunking — Large documents are automatically split into searchable chunks
• Context-aware — AI uses relevant chunks as context when generating responses

Trigger Words

Configure trigger words to control when the AI responds. Trigger words only gate the first message of a conversation — once triggered, all follow-up messages in that conversation receive AI responses.

Example trigger words: "hi", "hello", "help", "support", "info"

Agent Escalation

When the AI can't answer a question from the knowledge base, it automatically escalates the conversation to a human agent.

• AI uses the [ESCALATE_TO_AGENT] tag internally when unable to help
• The conversation is assigned to a random available agent
• Agent pool uses widget team members first, then falls back to the channel owner + team
• A notification is sent to the assigned agent

Widget AI Chat

The chat widget on your website also uses AI auto-reply:

• Visitors get instant AI responses based on your knowledge base
• If AI can't help, the conversation is escalated to a human agent
• Full conversation history is maintained for context

WhatsApp AI Auto-Reply

AI auto-reply for incoming WhatsApp messages works through the webhook handler:

• Incoming messages are checked against trigger words (first message only)
• AI searches the knowledge base for relevant context
• A response is generated and sent back via the WhatsApp API
• If the AI can't answer, the conversation is escalated to a human agent

Channel Management

Adding Channels

There are two ways for clients to add WhatsApp channels to the platform. The Superadmin controls which mode is active from Settings > Embedded Signup using a toggle switch:

1. Embedded Signup (Recommended) — Clients connect their WABA via Meta's guided Facebook Login flow. The superadmin manages one global webhook for all channels.
2. Manual Connection (Legacy) — Clients manually enter their WABA ID, Phone Number ID, and Access Token. Each client manages their own webhook configuration independently.

Embedded Signup Flow

Embedded Signup is the recommended way for clients to connect their WhatsApp Business Account. It uses Meta's guided flow so clients never need to manually copy API credentials.

Superadmin Prerequisites

Before clients can use Embedded Signup, the superadmin must complete these setup steps:

Callback URL: https://yourdomain.com/api/webhooks/whatsapp
Verify Token: your_webhook_verify_token

How It Works (Webhook Auto-Subscription)

Client Experience (Step-by-Step)

Once the superadmin has completed the setup above, clients follow this simple process:

1. Client goes to their Settings > Channels page and clicks "Add Channel"
2. A Facebook Login popup opens — client logs into their Facebook account
3. Client authorizes the app and selects their WhatsApp Business Account (WABA)
4. A processing dialog shows "Connecting your WhatsApp channel..."
5. The platform automatically retrieves the access token, phone number, and WABA details
6. The platform subscribes the WABA to the global webhook via subscribed_apps API
7. The channel is created, activated, and ready to use immediately

Clients do not need to configure any webhooks, create Meta Apps, or generate access tokens manually.

Manual Connection

Manual Connection is the legacy method where each client enters their own WhatsApp API credentials directly. This mode is useful when clients already have their own Meta App and want to manage their own API access independently.

When to Use Manual Mode

• Clients already have their own Meta App with WhatsApp configured
• Clients want full control over their own API credentials and webhook
• You don't want to go through Meta App Review for embedded signup permissions
• You're migrating from an older setup where clients already have access tokens

Superadmin Setup

To enable Manual mode, the superadmin simply turns OFF the Embedded Signup toggle in Settings > Embedded Signup. No Meta App credentials (App ID, App Secret, Config ID) are needed from the superadmin side when using manual mode.

Client Requirements

Each client must provide three credentials when adding a channel manually:

• WABA ID — WhatsApp Business Account ID, found in Meta Business Settings > Accounts > WhatsApp Accounts
• Phone Number ID — Found in the Meta App Dashboard under WhatsApp > API Setup > Phone number ID
• Access Token — A permanent system user token generated from the Meta Business Settings with whatsapp_business_management and whatsapp_business_messaging permissions

Webhook Setup (Per Client)

Channel Health Monitor

The platform automatically monitors channel health by periodically checking the WhatsApp Cloud API status for each connected channel.

• Runs daily at 2 AM (configurable)
• Checks phone number registration status
• Monitors messaging quality rating
• Sends notifications for health warnings or errors

Business Profile

Edit your WhatsApp Business Profile directly from the platform:

• Profile photo
• About text
• Business description
• Address, email, website
• Business category (vertical)

Coexistence Mode

Coexistence (dual-flow) allows using the WhatsApp Business App alongside the API. This is useful during migration from the Business App to the API.

Multi-Channel Switching

If a client has multiple WhatsApp channels, they can switch between them using the channel switcher in the sidebar. All data (contacts, conversations, campaigns) is automatically scoped to the selected channel.

Chat Widget

Widget Overview

The Chat Widget is an embeddable component that you can add to any website to enable live chat with your customers. It supports AI auto-replies, lead capture, and integrates with your platform's inbox.

Widget Installation

Add the following script to your website's HTML, just before the closing </body> tag:

<script>
  (function() {
    var s = document.createElement('script');
    s.src = 'https://yourdomain.com/widget.js';
    s.setAttribute('data-site-id', 'YOUR_SITE_ID');
    s.async = true;
    document.body.appendChild(s);
  })();
</script>

Replace YOUR_SITE_ID with the Site ID from your Widget Builder settings.

Customization

Customize the widget appearance in the Widget Builder:

• Colors — Primary color, background, text colors
• Position — Bottom-left or bottom-right of the page
• Welcome message — Initial greeting shown to visitors
• Brand name & logo — Displayed in the widget header
• Online/offline status — Show availability to visitors

Lead Capture

Before starting a chat, visitors are asked to provide their contact information:

• Name (required)
• Email (required)
• Phone number (optional)

This information is used to create or update contacts in your platform. Returning visitors (identified by email) resume their previous conversations.

Widget Conversations

Widget conversations appear in your platform inbox alongside WhatsApp conversations. They are identified with a "chatbot" platform tag.

Notifications

Notification Types

The platform supports 6 event types for notifications:

User Preferences

Each user can configure their notification preferences in Settings > Notifications:

• In-app notifications — Bell icon with unread badge in the header
• Email notifications — Send email alerts for events
• Sound alerts — Play a sound when notifications arrive

Email Templates

Superadmins can manage email notification templates in Settings > Notification Templates. Templates support variable substitution using {{varName}} syntax.

Sound Alerts

Sound notifications use the Web Audio API to play alert sounds when new events occur. Users can toggle sounds on/off per event type.

Plans & Billing

Creating Plans

Superadmins can create subscription plans with different feature sets and limits:

• Plan name and description
• Pricing — Monthly/yearly pricing
• Feature limits — Max contacts, messages/month, campaigns, team members, channels
• Module access — Enable/disable specific platform modules per plan

Plan Permissions

Each plan can include or exclude specific features:

• Inbox access
• Campaign management
• Automation flows
• AI auto-reply
• Analytics & reports
• Team management
• API access
• Widget builder

Payment Gateways

The platform supports two payment gateways:

Stripe Setup

Webhook URL: https://yourdomain.com/api/stripe/webhook

Razorpay Setup

Managing Subscriptions

The Superadmin can view all subscriptions, manually assign plans to clients, and manage billing through the Master Subscriptions page.

Roles & Permissions

Role Types

The platform has three user roles with hierarchical access:

Superadmin

Full platform control. There is typically one superadmin account.

• Manage all platform settings
• Create and manage subscription plans
• Configure payment gateways
• Manage embedded signup configuration
• View all users and their data
• Access system logs and health monitoring
• Manage notification email templates
• Configure branding and platform settings
• Manage languages and translations

Admin (Client)

Business owners who use the platform for their WhatsApp marketing.

• Connect and manage their WhatsApp channels
• Create and manage contacts, campaigns, templates
• Access inbox and respond to messages
• Set up automations and chatbots
• Invite and manage team members
• Configure AI settings for their channels
• Access analytics and reports
• Access features based on their subscription plan

Team Member

Staff members invited by Admin users.

• Access inbox and respond to assigned conversations
• View contacts (read-only based on permissions)
• Limited access based on permissions assigned by admin

Permission System

The platform uses Role-Based Access Control (RBAC) with both backend middleware (requireRole) and frontend route guards (PermissionRoute). Admins can configure granular permissions for team members.

REST API Reference

Authentication

All API requests require authentication using an API key passed in the request header:

curl -X GET https://yourdomain.com/api/v1/contacts \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

Generate API keys from your dashboard under Settings > API Keys.

Rate Limits

API rate limits are enforced based on your subscription plan:

Endpoints Overview

The REST API provides access to the following resources:

Contacts

Messages

Campaigns

Templates

Error Handling

The API uses standard HTTP status codes:

Error responses follow this format:

{
  "error": true,
  "message": "Descriptive error message",
  "code": "ERROR_CODE"
}

Outbound Webhooks

Configure webhook URLs to receive real-time event notifications from the platform. When events occur (new message, campaign completed, etc.), the platform sends a POST request to your configured URL.

Webhook Payload Format

{
  "event": "message.received",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "messageId": "msg_abc123",
    "conversationId": "conv_xyz789",
    "from": "+1234567890",
    "body": "Hello, I need help",
    "type": "text"
  }
}

Available Webhook Events

• message.received — New incoming message
• message.status — Message delivery status change
• campaign.completed — Campaign finished
• campaign.failed — Campaign failed
• contact.created — New contact created
• template.approved — Template approved by Meta
• template.rejected — Template rejected by Meta

Environment Variables

Core Variables

Database

Meta / WhatsApp

Payment Gateways

Email / SMTP

AI Providers

File Storage

Troubleshooting

Webhook Issues

Webhook not receiving messages

• Verify the webhook URL is correct: https://yourdomain.com/api/webhooks/whatsapp
• Confirm the Verify Token in Meta matches your WEBHOOK_VERIFY_TOKEN env variable
• Check that you've subscribed to the messages webhook field
• Ensure your SSL certificate is valid (webhooks require HTTPS)
• Check server logs for incoming webhook requests: pm2 logs chatlix

Webhook verification failing

# Test webhook verification manually
curl "https://yourdomain.com/api/webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=test123"

If this returns test123, your webhook verification is working correctly.

Message Delivery Issues

Messages not sending

• Check that the access token is valid and not expired
• Verify the phone number is registered and active
• For non-template messages, ensure you're within the 24-hour messaging window
• Check the Meta API status page for any outages
• Review error messages in the platform's message logs

Messages stuck as "sending"

• Check the message status cron job is running
• Verify the WhatsApp API is responding correctly
• Check for rate limiting from Meta

Template Rejection

Common reasons for template rejection:

• Misleading content — Don't use deceptive language or false claims
• Missing opt-out — Marketing templates must include an opt-out mechanism
• Prohibited content — No gambling, adult content, or illegal activities
• Variable misuse — Variables shouldn't change the template's meaning
• URL shorteners — Avoid shortened URLs in templates
• Formatting issues — Excessive capitalization, special characters, or emojis

Connection Problems

Embedded Signup failing

• Ensure the Facebook Login for Business product is added to your Meta app
• Verify the Config ID is correct in the Embedded Signup settings
• Check that your domain is in the "Valid OAuth Redirect URIs"
• Make sure third-party cookies are not blocked in the user's browser

Channel showing "Disconnected"

• The access token may have expired — try reconnecting the channel
• The phone number may have been deregistered from WhatsApp
• Check the Channel Health Monitor for specific error messages

Performance

• Slow page loads — Check database query performance, add indexes if needed
• High memory usage — Monitor with pm2 monit, consider upgrading server
• Database connections — Use connection pooling (built into Drizzle/Neon)
• File uploads — Move to cloud storage (S3/DigitalOcean Spaces) for better performance

Common Errors

Error: (#131047) Re-engagement message

You're trying to send a free-form message outside the 24-hour window. Use an approved template instead.

Error: (#100) Invalid parameter

Check that all required fields are provided and correctly formatted. Common causes: invalid phone number format, missing template variables.

Error: (#130429) Rate limit hit

You've exceeded Meta's messaging rate limit. Reduce sending speed or wait before retrying. Higher messaging tiers allow more messages.

Error: (#33) Phone number deleted

The phone number has been deregistered from WhatsApp. Re-register it through the Meta Business Manager or remove the channel from the platform.

Database connection error

Check your DATABASE_URL is correct and the database server is accessible. For managed databases, verify the SSL mode setting.

Support & Help

Raise a Support Ticket

For any technical support, bugs, feature requests, or installation assistance, please raise a ticket through our dedicated support portal:

Before Raising a Ticket

To help us resolve your issue faster, please include the following information in your support ticket:

• Platform version — The version or commit hash of your deployment
• Environment details — Server OS, Node.js version, database type
• Steps to reproduce — Clear steps to replicate the issue
• Error logs — Relevant logs from PM2 (pm2 logs chatlix) or browser console
• Screenshots — Visual evidence of the issue, if applicable

Additional Resources

• Meta WhatsApp Documentation — developers.facebook.com/docs/whatsapp
• WhatsApp Business Platform Overview — developers.facebook.com/docs/whatsapp/overview
• WhatsApp Cloud API Reference — developers.facebook.com/docs/whatsapp/cloud-api/reference
• Meta Business Help Center — facebook.com/business/help
• Meta Developer Community — developers.facebook.com/community