ChatFlow Documentation

What is ChatFlow?

ChatFlow is a complete, multi-tenant AI-powered customer support platform that allows businesses to provide instant customer support through an embeddable chat widget. Built with Laravel 12 and Next.js 14, it offers:

File Structure

chatflow/
├── frontend/          # Next.js 14 Application
│   ├── src/
│   │   ├── app/       # App Router pages
│   │   ├── components/# React components
│   │   ├── contexts/  # React contexts
│   │   ├── hooks/     # Custom hooks
│   │   └── libs/      # Utilities & API client
│   └── public/        # Static assets
│
├── backend/           # Laravel 12 API
│   ├── app/
│   │   ├── Http/Controllers/  # API Controllers
│   │   ├── Models/            # Eloquent Models
│   │   └── Services/          # Business Logic
│   ├── database/
│   │   ├── migrations/        # Database schema
│   │   └── seeders/           # Demo data
│   └── routes/api.php         # API routes
│
├── install.sh         # One-click installer
├── start.sh           # Development server starter
└── .env.example       # Environment template

Server Requirements

Backend Requirements

PHP Extensions Required

• BCMath PHP Extension
• Ctype PHP Extension
• JSON PHP Extension
• Mbstring PHP Extension
• OpenSSL PHP Extension
• PDO PHP Extension
• Tokenizer PHP Extension
• XML PHP Extension
• cURL PHP Extension

Recommended Hosting

ChatFlow works best with these hosting providers:

• VPS/Dedicated: DigitalOcean, AWS EC2, Linode, Vultr
• Shared Hosting: Any cPanel hosting with SSH access and Node.js support
• Platform: Laravel Forge, Ploi, ServerPilot

Installation

Quick Installation (Recommended)

The easiest way to install ChatFlow is using our one-click installer. The installer requires a .env file at the project root before it runs.

unzip chatflow.zip -d /var/www/chatflow
cd /var/www/chatflow

cp .env.example .env
nano .env

chmod +x install.sh
./install.sh

cd backend && php artisan db:seed && cd ..

./start.sh

Manual Installation

If the installer fails or you prefer manual installation:

Backend Setup

Create the MySQL database first. Then:

cd backend
composer install
cp .env.example .env
# Edit .env: APP_URL, DB_DATABASE, DB_USERNAME, DB_PASSWORD
php artisan key:generate
php artisan migrate
php artisan db:seed   # Optional: demo data
php artisan serve     # Backend at http://localhost:8000

Frontend Setup

Create frontend/.env.local (there is no .env.example in frontend). Set at least:

NEXT_PUBLIC_API_URL=http://localhost:8000

Optionally: NEXT_PUBLIC_REVERB_HOST, NEXT_PUBLIC_REVERB_PORT, NEXT_PUBLIC_REVERB_KEY.

cd frontend
npm install
# Create .env.local with the vars above
npm run dev           # Frontend at http://localhost:3000

Configuration

Environment Variables

Install flow: Use .env at the project root. The installer copies it to backend/.env and generates frontend/.env.local from APP_URL, FRONTEND_URL, etc. Edit root .env before running ./install.sh.

Manual setup: Configure backend/.env and frontend/.env.local directly. Main variables:

Application Settings

# Application
APP_NAME=ChatFlow
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

# Frontend URL (for CORS)
FRONTEND_URL=https://yourdomain.com

Database Configuration

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=chatflow
DB_USERNAME=your_username
DB_PASSWORD=your_password

Frontend Environment

When using the installer, frontend/.env.local is generated from root .env (APP_URL, FRONTEND_URL, REVERB_*). For manual setup, create frontend/.env.local with at least NEXT_PUBLIC_API_URL (backend base URL).

Key variables:

# API URL
NEXT_PUBLIC_API_URL=https://api.yourdomain.com

# WebSocket URL (if using Reverb)
NEXT_PUBLIC_REVERB_APP_KEY=your-reverb-key
NEXT_PUBLIC_REVERB_HOST=ws.yourdomain.com
NEXT_PUBLIC_REVERB_PORT=443

Frontend Setup

Development Mode

cd frontend
npm run dev

Access at http://localhost:3000

Production Build

# Build for production
npm run build

# Start production server
npm start

Customizing the Frontend

Changing Colors

Edit frontend/tailwind.config.js to customize the color scheme:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#f0f9ff',
          500: '#3b82f6',  // Main primary color
          600: '#2563eb',
          700: '#1d4ed8',
        }
      }
    }
  }
}

Changing Logo

Replace the logo files in frontend/public/:

• logo.svg - Main logo
• logo-dark.svg - Dark mode logo
• favicon.ico - Browser favicon

Modifying Pages

All pages are located in frontend/src/app/:

Backend Setup

API Structure

The backend API follows RESTful conventions:

Running Queue Workers

For email sending and background jobs:

php artisan queue:work

Running Scheduler

Add to crontab for scheduled tasks:

* * * * * cd /var/www/chatflow/backend && php artisan schedule:run >> /dev/null 2>&1

Database

Database Schema

ChatFlow uses the following main tables:

Create Database First

Before running migrations, create the MySQL database (e.g. CREATE DATABASE chatflow; or via phpMyAdmin). For SQLite, set DB_CONNECTION=sqlite and ensure database/database.sqlite exists.

Running Migrations

# Run all migrations
php artisan migrate

# Reset and re-run migrations
php artisan migrate:fresh

# Rollback last migration
php artisan migrate:rollback

Seeding Demo Data

# Seed all demo data
php artisan db:seed

# Seed specific seeder
php artisan db:seed --class=DemoSeeder

Authentication

Authentication System

ChatFlow uses Laravel Sanctum for token-based authentication. When a user logs in, they receive an API token that must be included in subsequent requests.

Login Flow

1. User submits email and password to /api/v1/auth/login
2. Server validates credentials and returns a token
3. Token is stored in localStorage/cookies
4. Token is sent in Authorization: Bearer {token} header

Registration Flow

When a new user registers:

1. A new Tenant is created
2. The user becomes the tenant admin
3. Default widget is created for the tenant

User Roles

Widget Integration

As a Customer, you get simple Chat and Knowledge Base (Help Center) embed codes from Dashboard → Widget. Copy → paste on your site → the system works. No extra setup. Add the Chat snippet before </body>; for KB, save the full HTML as e.g. help.html and upload to your site. Visitors use chat and the help center on those pages. Replying and creating only on the platform (Dashboard).

Embedding the Chat Widget

Add the chat widget to your own page by including this code before the closing </body> tag:

<script>
  (function(w,d,s,o,f,js,fjs){
    w['ChatFlowWidget']=o;w[o]=w[o]||function(){
    (w[o].q=w[o].q||[]).push(arguments)};
    js=d.createElement(s),fjs=d.getElementsByTagName(s)[0];
    js.id=o;js.src=f;js.async=1;fjs.parentNode.insertBefore(js,fjs);
  }(window,document,'script','chatflow','https://yourdomain.com/widget.js'));
  chatflow('init', 'YOUR_WIDGET_API_KEY');
</script>

Getting Your API Key & Embed Codes

Simple flow: Copy the code → paste on your site → system works.

1. Log in to your dashboard
2. Go to Widget (Widget Settings)
3. Copy the Chat embed code and paste it before </body> on your site
4. Copy the Knowledge Base / Help Center code, save as help.html (or paste into a page), and upload to your site (e.g. yoursite.com/help.html)

Widget Customization

Customize the widget appearance from the dashboard:

Testing Embeds

The package includes example pages to test your widget and Help Center integration locally:

Knowledge Base

The Knowledge Base (Help Center) allows your customers to create self-service support content. Visitors can search and browse articles without contacting support.

Overview

Each tenant gets their own Knowledge Base with:

• Categories - Organize articles into topics (e.g., "Getting Started", "Billing", "API")
• Articles - Help content with rich text, code blocks, images
• Search - Full-text search across all articles
• Public Embed - Embeddable help center for your website

Managing Categories

Navigate to Dashboard → Knowledge Base to manage your help content.

Creating a Category

1. Go to Dashboard → Knowledge Base
2. Click "New Category"
3. Enter category name (e.g., "Getting Started")
4. Optionally add a description and icon
5. Set the display order
6. Click Save

Managing Articles

Creating an Article

1. Go to Dashboard → Knowledge Base
2. Select a category or click "New Article"
3. Enter the article title
4. Select the category
5. Write the content using the rich text editor
6. Set status: Draft or Published
7. Click Save

Article Features

Embedding the Help Center

You can embed a complete Help Center on your website. Get the embed code from Dashboard → Widget.

Help Center Embed

The Help Center embed code creates a full-page help center. Save it as an HTML file (e.g., help.html) on your website:

<!-- Example: help.html -->
<!DOCTYPE html>
<html>
<head>
    <title>Help Center</title>
</head>
<body>
    <div id="chatflow-help"></div>
    <script src="https://yourdomain.com/help-center.js"></script>
    <script>
        ChatFlowHelp.init('YOUR_WIDGET_API_KEY');
    </script>
</body>
</html>

API Endpoints

Knowledge Base has dedicated API endpoints:

Public Access

Published articles are accessible via the public API (no authentication required, but requires valid widget API key):

• /api/public/knowledge/categories?api_key=YOUR_KEY - List categories
• /api/public/knowledge/articles?api_key=YOUR_KEY - List articles
• /api/public/knowledge/articles/{id}?api_key=YOUR_KEY - Get article by ID
• POST /api/public/knowledge/articles/{id}/feedback?api_key=YOUR_KEY - Submit article feedback

AI Configuration

OpenAI Integration

ChatFlow supports OpenAI for automated responses. Each tenant can configure their own API key (BYOK - Bring Your Own Key model).

Setting Up AI

1. Get an API key from OpenAI Platform
2. Go to Dashboard → Settings → AI
3. Enter your OpenAI API Key
4. Select your preferred model
5. Enable AI responses

Supported Models

• gpt-4o - Most capable, recommended
• gpt-4o-mini - Fast and cost-effective
• gpt-4-turbo - High performance
• gpt-3.5-turbo - Budget-friendly

AI Settings

Email Setup

Email Configuration

ChatFlow supports multiple email providers. Configure via System Admin panel or environment variables.

SMTP Configuration

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=587
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="${APP_NAME}"

Supported Providers

• SMTP - Any SMTP server
• Mailgun - Mailgun API
• Amazon SES - AWS Simple Email Service
• Postmark - Postmark API

Email Templates

Customize email templates from System Admin → Settings → Email:

• Welcome Email
• Password Reset
• New Conversation Notification
• Subscription Confirmation

Payment Setup (Stripe & PayPal)

ChatFlow supports both Stripe and PayPal for subscription billing. Configure your preferred payment provider from the System Admin panel.

Stripe Integration

Setting Up Stripe

1. Create a Stripe account
2. Get your API keys from Dashboard → Developers → API Keys
3. Go to System Admin → Settings → Payment
4. Enter your Publishable Key and Secret Key
5. Set up your Webhook endpoint

Stripe Webhook Setup

Configure a webhook in Stripe Dashboard pointing to:

https://yourdomain.com/api/webhooks/stripe

Required events:

• checkout.session.completed
• customer.subscription.updated
• customer.subscription.deleted
• invoice.payment_succeeded
• invoice.payment_failed

PayPal Integration

Setting Up PayPal

1. Create a PayPal Developer account
2. Create an App in the Developer Dashboard
3. Get your Client ID and Secret
4. Go to System Admin → Settings → Payment
5. Enter your PayPal credentials
6. Select mode: Sandbox (testing) or Live (production)

PayPal Webhook Setup

Configure a webhook in PayPal Developer Dashboard pointing to:

https://yourdomain.com/api/webhooks/paypal

Required events:

• BILLING.SUBSCRIPTION.ACTIVATED
• BILLING.SUBSCRIPTION.UPDATED
• BILLING.SUBSCRIPTION.CANCELLED
• BILLING.SUBSCRIPTION.EXPIRED
• PAYMENT.SALE.COMPLETED
• PAYMENT.SALE.DENIED

Selecting Active Provider

In System Admin → Settings → Payment, select your active payment provider:

• None - Payments disabled
• Stripe - Use Stripe for checkout
• PayPal - Use PayPal for checkout

Pricing Plans

Configure pricing plans from System Admin → Settings → Payment:

• Plan names and descriptions
• Monthly/yearly prices
• Feature limits per plan

Real-time (WebSocket)

Laravel Reverb

ChatFlow uses Laravel Reverb for real-time messaging. This enables instant message delivery without page refresh.

Configuration

# backend/.env
BROADCAST_CONNECTION=reverb

REVERB_APP_ID=your-app-id
REVERB_APP_KEY=your-app-key
REVERB_APP_SECRET=your-app-secret
REVERB_HOST=localhost
REVERB_PORT=8080

Starting Reverb Server

php artisan reverb:start

Production Setup

For production, use a process manager like Supervisor:

[program:reverb]
process_name=%(program_name)s
command=php /var/www/chatflow/backend/artisan reverb:start
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/reverb.log

White-Label Configuration

Complete Rebranding

ChatFlow is fully white-label ready. You can completely rebrand it for your business or clients.

Branding Settings

Configure from System Admin → Settings → Branding:

Email Branding

Email templates automatically use your branding:

• {{app_name}} - Your site name
• {{logo_url}} - Your logo
• {{support_email}} - Support email

Code-Level Customization

For deeper customization:

• Colors: frontend/tailwind.config.js
• Fonts: frontend/src/app/layout.tsx
• Static Text: Component files in frontend/src/components/

Admin Panel (Tenant Dashboard)

Dashboard Overview

The tenant admin dashboard provides complete control over your support operations.

Dashboard Sections

Agent Invitation (How Agents Join the System)

Agents (team members who reply to conversations) join your workspace via invitation. The admin or owner invites them from the dashboard; they receive an email, set their password, then log in.

Step 1: Admin invites an agent

1. Go to Dashboard → Team (/dashboard/team).
2. Click Invite or Add agent.
3. Enter the agent's name, email, and role (admin, agent, or viewer). Optionally set skills, departments, and max concurrent chats.
4. Click Save or Send invitation.

The system creates the user account and sends an invitation email containing a unique link.

Step 2: Agent receives the email

The email uses the Team Invitation template (see Email Setup). It includes a button such as Accept Invitation that links to:

https://yourdomain.com/accept-invitation?token=...

The token is valid for 7 days. If it expires, the admin must invite the user again.

Step 3: Agent sets their password

1. The agent clicks the link and lands on /accept-invitation.
2. The page validates the token and shows a Set your password form (and optionally the account email).
3. The agent enters a password, confirms it, and submits.
4. The system saves the password and clears the invitation token.

Step 4: Agent logs in

The agent goes to /login, signs in with their email and the password they just set, and can then access the dashboard according to their role.

Summary

System Admin Panel

Super Admin Access

The System Admin panel is only accessible to users with is_super_admin=true.

Creating a Super Admin

The super admin is automatically created when you run the database seeder:

# Run all seeders (includes super admin creation)
php artisan db:seed

# Default super admin credentials:
# Email: super@admin.com
# Password: password

# Or manually via tinker
php artisan tinker
>>> User::where('email', 'your@email.com')->update(['is_super_admin' => true]);

System Admin Features

Deployment

Production Checklist

Nginx Configuration

Backend (Laravel)

server {
    listen 80;
    server_name api.yourdomain.com;
    root /var/www/chatflow/backend/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;
    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Frontend (Next.js)

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Process Manager (Supervisor)

Queue worker:

[program:chatflow-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/chatflow/backend/artisan queue:work --sleep=3 --tries=3
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/chatflow-worker.log

Reverb (WebSocket)

For real-time chat, run the Reverb server. Development: php artisan reverb:start. Production: use Supervisor, e.g.:

[program:chatflow-reverb]
command=php /var/www/chatflow/backend/artisan reverb:start
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/chatflow-reverb.log

Troubleshooting

Common Issues

cp .env.example .env
nano .env   # Set APP_URL, DB_*

tail -f backend/storage/logs/laravel.log

FRONTEND_URL=https://yourdomain.com

chmod -R 775 backend/storage
chmod -R 775 backend/bootstrap/cache
chown -R www-data:www-data backend/storage
chown -R www-data:www-data backend/bootstrap/cache

Getting Help

If you can't resolve an issue:

1. Check the Troubleshooting section
2. Search existing support tickets
3. Contact support with:
• Error message/screenshot
• Laravel log contents
• Browser console errors
• Steps to reproduce

Changelog

License

This software is licensed under the terms in LICENSE.txt (Envato Regular / Extended License).

• Regular License: Use for one end product (free or paid to client); modify and combine with other works.
• Extended License: Same as Regular; you may also sell the end product (e.g. SaaS) or charge for access.

You may not redistribute, resell, or use the Software in competing products. Full terms, restrictions, support, and updates policy: see LICENSE.txt in the package root.

For licensing questions: support@webkoding.com

Support

Support Policy

• We respond to all tickets within 24-48 hours (business days)
• Support includes help with bugs and installation issues
• Customization requests are outside support scope
• Please include detailed information when reporting issues

Before Contacting Support

1. Read this documentation thoroughly
2. Check the Troubleshooting section
3. Ensure you're using the latest version
4. Test on a fresh installation if possible