“AI Chatbot SaaS Platform” Complete Documentation v1.0

“AI Chatbot SaaS Platform”

Created: 2025
By: LendaSoft
Email: LendaLabs@gmail.com
Version: 1.0

Thank you for choosing our AI Chatbot SaaS Platform! This comprehensive documentation will guide you through installation, configuration, and usage. If you have any questions, please contact our support team.

Table of Contents

  1. Installation & Setup
  2. Environment Variables & API Keys
  3. Admin Settings Configuration
  4. Build & Deployment Guide
  5. Creating Your First Chatbot
  6. Widget Integration
  7. Website Usage Guide
  8. Key Features
  9. Troubleshooting
  10. Support

A) Installation & Setup - top

🚀 Quick Start Guide

Follow these steps to get started:

Prerequisites

Step 1: Install Dependencies

Install all required npm packages:

npm install

Note: This may take a few minutes depending on your internet connection. Make sure you have a stable connection.

Step 2: Environment Variables Setup

Create a .env file in the root directory. Copy from .env.example if available:

cp .env.example .env

Or create manually. See Section B for detailed API key setup.

Step 3: Database Setup

Generate Prisma client and push schema to database:

npm run db:generate npm run db:push

Step 4: Create Admin Account

Create your first admin user:

npm run create-admin

Or with custom credentials:

npm run create-admin admin@example.com YourPassword123 "Admin Name"

Step 5: Start the Application

Development Mode:

npm run dev

Production Mode:

npm run build npm start

✅ Success! Your application should now be running at http://localhost:3000

B) Environment Variables & API Keys - top

🔑 Required API Keys

You need to configure these in your .env file:

1. Database Configuration (DATABASE_URL)

Option A: Local PostgreSQL
  1. Install PostgreSQL from postgresql.org
  2. Create a database:
    psql -U postgres CREATE DATABASE chatflow; \q
  3. Add to .env:
    DATABASE_URL="postgresql://postgres:YourPassword@localhost:5432/chatflow"
Option B: Supabase (Free Cloud Database - Recommended)
  1. Go to supabase.com and create a free account
  2. Create a new project
  3. Go to Settings → Database → Connection String
  4. Copy the URI and paste into .env

2. AI API Keys

🌟 Recommended: Google Gemini API

Why Gemini? Gemini offers excellent performance, competitive pricing, and is recommended for this platform.

Getting Gemini API Key:
  1. Go to Google AI Studio
  2. Sign in with your Google account
  3. Click "Create API Key"
  4. Select or create a Google Cloud project
  5. Copy the API key (starts with AIza...)
  6. Add to .env:
    GEMINI_API_KEY="AIzaSy..."
Alternative: OpenAI API Key
  1. Go to platform.openai.com and create an account
  2. Navigate to API Keys
  3. Click "Create new secret key"
  4. Copy the key (shown ONLY ONCE - save it!)
  5. Add billing information (minimum $5 credit)
  6. Add to .env:
    OPENAI_API_KEY="sk-proj-..."
🚀 OpenRouter Embeddings

If you want to use Anthropic Claude, Meta Llama, Mistral, or hundreds of other models instead of OpenAI, you can use OpenRouter as a full replacement, including for Knowledge Base Embeddings!

Setting up OpenRouter for Everything:
  1. Go to OpenRouter.ai and create an account
  2. Navigate to Keys and click Create Key
  3. Add credits to your account if needed
  4. Update your .env file to override the OpenAI Base URL and Key:
    OPENAI_API_KEY="sk-or-v1-your-openrouter-key" OPENAI_BASE_URL="https://openrouter.ai/api/v1"
  5. Now you can enter any OpenRouter Model ID (e.g., anthropic/claude-3.5-sonnet) in your Dashboard for chat responses!
🔥 Using OpenRouter for RAG & Knowledge Base (Embeddings)

When users upload PDF or Text files to train the AI (Knowledge Base), the system needs to convert text into vectors (Embeddings). OpenRouter natively supports embedding models and serves as a direct proxy!

By just setting the OPENAI_BASE_URL to OpenRouter as shown above, all embedding requests will automatically be routed through OpenRouter seamlessly without requiring any separate real OpenAI key.

3. JWT Secret Key

Generate a secure random key (minimum 32 characters):

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Add to .env:

JWT_SECRET="your-generated-secret-key-here-minimum-32-characters"

4. Application URL

NEXT_PUBLIC_APP_URL="http://localhost:3000"

For production, change to your domain:

NEXT_PUBLIC_APP_URL="https://yourdomain.com"

5. Stripe Configuration (Optional - for payments)

  1. Go to Stripe Dashboard and create an account
  2. Navigate to Developers → API Keys
  3. Copy Secret key (starts with sk_test_ for test mode)
  4. Copy Publishable key (starts with pk_test_)
  5. Add to .env:
    STRIPE_SECRET_KEY="sk_test_..." NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
  6. For webhooks, install Stripe CLI and run:
    stripe listen --forward-to localhost:3000/api/stripe/webhook
  7. Copy the webhook secret and add:
    STRIPE_WEBHOOK_SECRET="whsec_..."

6. PayPal Configuration (Optional - for payments)

  1. Go to the PayPal Developer Dashboard
  2. Navigate to Apps & Credentials
  3. Create a new app or open an existing one
  4. Copy your Client ID and Secret Key
  5. Add to .env:
    NEXT_PUBLIC_PAYPAL_CLIENT_ID="your_client_id_here" PAYPAL_CLIENT_SECRET="your_secret_key_here" PAYPAL_MODE="sandbox" # Use "live" for production

Complete .env File Example

# Database DATABASE_URL="postgresql://postgres:password@localhost:5432/chatflow" # JWT Secret (generate randomly) JWT_SECRET="your-32-character-secret-key-here" # AI API Keys (Gemini recommended) GEMINI_API_KEY="AIzaSy..." OPENAI_API_KEY="sk-proj-..." # Optional # Application URL NEXT_PUBLIC_APP_URL="http://localhost:3000" # Stripe (Optional) STRIPE_SECRET_KEY="sk_test_..." NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..." STRIPE_WEBHOOK_SECRET="whsec_..." # PayPal (Optional) NEXT_PUBLIC_PAYPAL_CLIENT_ID="your_client_id" PAYPAL_CLIENT_SECRET="your_secret" PAYPAL_MODE="sandbox"

C) Admin Settings Configuration - top

⚙️ Important Admin Settings

After logging in as admin, configure these essential settings:

Step 1: Access Admin Panel

  1. Go to http://localhost:3000/login
  2. Login with your admin credentials
  3. You'll be redirected to /admin dashboard

Step 2: Configure Domain Settings

  1. Go to Admin → Settings (or /admin/settings)
  2. Find "App Base URL" or "Domain Settings" section
  3. Update the domain URL:
    • Development: http://localhost:3000
    • Production: https://yourdomain.com
  4. Click "Save"

Important: The domain URL is used for widget integration. Make sure it matches your actual domain in production!

Step 3: Configure Stripe Settings

  1. In Admin Settings, find "Payment Settings" or "Stripe Configuration"
  2. Enter your Stripe keys:
    • Stripe Secret Key: From your .env file
    • Stripe Publishable Key: From your .env file
    • Webhook Secret: From Stripe CLI or dashboard
  3. Click "Save" to save Stripe keys

Step 3.5: Configure Stripe Price IDs (Important!)

⚠️ Important: You must configure Stripe Price IDs for subscription plans to work correctly!

  1. Go to Admin → Settings → Subscriptions tab (or navigate to /admin/settings and click on "Subscriptions" tab)
  2. You'll see subscription plan settings for STARTER, PROFESSIONAL, and ENTERPRISE plans
  3. For each subscription plan, you need to set the Stripe Price ID in the "Stripe Price ID" field:
    • How to get Stripe Price ID:
      1. Go to Stripe Dashboard → Products
      2. Create a product for each plan (or use existing ones)
      3. Add a price to each product
      4. Copy the Price ID (starts with price_)
      5. Example: price_1ABC123def456GHI789
    • Enter Price IDs:
      • Free Plan Price ID: Usually leave empty or set to null
      • Basic Plan Price ID: Enter your Stripe Price ID (e.g., price_1ABC123...)
      • Pro Plan Price ID: Enter your Stripe Price ID
      • Enterprise Plan Price ID: Enter your Stripe Price ID
  4. Make sure each Price ID matches the correct plan and billing cycle (monthly/yearly)
  5. Click "Save" or "Update" for each plan

💡 Tip: Stripe Price IDs are unique identifiers for each pricing tier. They link your subscription plans to Stripe's payment system. Without correct Price IDs, users won't be able to subscribe to paid plans.

Example Stripe Price IDs: Free Plan: (empty or null) Basic Plan: price_1ABC123def456GHI789 Pro Plan: price_1XYZ789ghi012JKL345 Enterprise Plan: price_1MNO456pqr789STU012

Step 3.6: Configure PayPal Settings

  1. In Admin Settings, find the "Payment Settings" section
  2. Toggle Enable PayPal if you wish to offer it alongside or instead of Stripe.
  3. Make sure your PayPal keys are correctly set in the .env file.

Step 4: General Settings

  1. Configure Site Name and Site Description
  2. Set Contact Email for support
  3. Configure SEO Settings (meta tags, keywords)
  4. Set Email Settings (SMTP configuration if needed)
  5. Save all changes

✅ Configuration Complete! Your admin settings are now configured. You can start creating chatbots.

D) Build & Deployment Guide - top

🔨 Production Build Steps

For detailed build instructions, see the Build Guide document.

Quick Build Summary

  1. Install Dependencies:
    npm install
  2. Generate Prisma Client:
    npm run db:generate
  3. Set Up Environment Variables:

    Ensure your .env file is properly configured (see Section B)

  4. Run Database Migrations:
    npm run db:push
  5. Build the Application:
    npm run build

    This will compile TypeScript, optimize assets, and create a production-ready build in the .next directory.

  6. Start Production Server:
    npm start

    The application will be available at http://localhost:3000 (or your configured port).

📖 Full Build Documentation

For comprehensive build instructions, troubleshooting, and deployment options, see:

⚠️ Build Troubleshooting

If you encounter build errors:

See Build Guide - Troubleshooting Section for detailed solutions.

E) Creating Your First Chatbot - top

  1. Go to Dashboard → Chatbots → Create New
  2. Fill in basic information:
    • Chatbot name
    • Description (optional)
    • Language
  3. Configure AI:
    • Select AI model (Gemini recommended)
    • Write AI instructions
    • Set welcome message
  4. Add Knowledge Base (optional):
    • Create entries with titles and content
    • Enable/disable as needed
  5. Click "Save Chatbot"

F) Widget Integration - top

  1. Go to your chatbot's settings page
  2. Navigate to "Widget" tab
  3. Choose integration method:
    • HTML Integration: Copy code and paste before </body>
    • WordPress Plugin: Download and install plugin
    • Shopify Liquid: Use Liquid code for Shopify stores
  4. Copy the widget code
  5. Paste into your website

G) Website Usage Guide - top

1. User Registration & Login

  1. Go to /register to create a new account
  2. Fill in email, password, and name
  3. Verify email (if enabled)
  4. Login at /login

2. Dashboard Overview

After login, you'll see:

3. Creating a Chatbot

  1. Click "New Chatbot" button
  2. Fill in chatbot details
  3. Configure AI settings
  4. Add knowledge base entries
  5. Save and get widget code

4. Managing Conversations

  1. Go to Conversations section
  2. View all chat history
  3. Filter by chatbot or date
  4. Export conversations if needed

5. Widget Customization

  1. Go to chatbot settings → Appearance tab
  2. Customize colors, fonts, position
  3. Preview changes in real-time
  4. Save and deploy

6. E-commerce Integration

  1. Go to chatbot settings → E-commerce tab
  2. Enable WooCommerce or Shopify
  3. Enter API credentials
  4. Test product search functionality

H) Key Features - top

🤖 AI Models

Support for multiple AI models:

📸 Image Recognition

Chatbots can analyze images uploaded by users using vision-capable models.

💬 Conversations

View and manage all customer conversations from the dashboard with search and filtering.

🎯 Lead Capture

Automatically capture leads from conversations (emails, phones, company names).

📊 Analytics

Track chatbot performance, response times, and customer satisfaction metrics.

🎫 Support Tickets

Manage support tickets and customer issues directly from the platform.

📚 Knowledge Base

Add knowledge base entries to help chatbots answer specific questions accurately.

🛒 E-commerce Integration

Integrate with WooCommerce and Shopify for product search, cart management, and order tracking.

I) Troubleshooting - top

Application won't start

Solution: Check Node.js version (18+), verify database connection, ensure all dependencies are installed with npm install.

Database connection error

Solution: Verify DATABASE_URL in .env file, ensure database server is running, check credentials, make sure database exists.

AI not responding

Solution: Check API keys are set correctly (GEMINI_API_KEY or OPENAI_API_KEY), verify API key has credits, check selected AI model is available, ensure billing is active.

Widget not appearing

Solution: Verify widget script is added before </body> tag, check chatbot ID is correct, verify API URL is accessible, check CORS settings, ensure domain is configured in admin settings.

Images not being analyzed

Solution: Ensure you're using a vision-capable model (Gemini models, GPT-4o, GPT-5), check file size is under 5MB, verify API key supports vision features.

Stripe payments not working

Solution: Verify Stripe keys in .env and admin settings, check webhook is configured correctly, ensure you're using test keys in development, verify webhook secret matches.

Port already in use

Solution: Change the port or kill the process:

J) Support - top

Getting Help:

System Requirements:

Recommended Setup:

🚀 Ready to Start?

You now have everything you need to create and deploy AI-powered chatbots. Follow the steps above to:

  1. Install dependencies with npm install
  2. Configure environment variables
  3. Set up admin settings
  4. Create your first chatbot
  5. Integrate the widget into your website

Start by creating your first chatbot and integrate it into your website!

Thank you for choosing our AI Chatbot SaaS Platform!

LendaSoft

Go To Table of Contents