Platform Requirements

System dependencies, host hardware resources, network ports configuration, database structures, and third-party API credentials needed to deploy CallVIQ.

CallVIQ runs on a self-hosted Node.js process architecture, utilizing PM2 process management, Nginx reverse proxying, and system service managers to coordinate REST API gateways, real-time media WebSockets, queue workers, database pools, and frontend client views. Ensure your deployment host meets the resource limits and connectivity conditions listed below.

System & Service Specifications

The following table lists the physical resources, database software configurations, and runtime dependencies required to launch the CallVIQ application stack:

Supported Provider Integrations

CallVIQ V2.0 operates on a dynamic, multi-provider architecture. Connect your own API credentials to route calls, synthesize voices, and process speech models across the following supported providers:

Platform Branding

Configure your platform logo, custom title, dynamically style login screens, and set brand identity variables.

CallVIQ contains a built-in Branding Engine accessible via the Super Admin Dashboard. These settings dynamically apply brand styling across your tenant panels, login pages, navigation bars, and transactional emails. You can configure your branding automatically through the admin panel or manually by modifying the source files.

Branding Configuration Matrix

The following table lists the core branding assets, their descriptions, file paths, and recommended specifications:

Option 1: Dynamic Dashboard Configuration (Recommended)

Follow these steps to configure your custom white-label branding dynamically via the web user interface without editing any source code files:

Step 1: Log in to the Super Admin Dashboard

Open your browser and navigate to the admin portal at http://localhost:3000/superadmin/login (or your live production domain). Enter your Super Admin operator credentials (default is admin@callviq.com / Admin@123456) and authenticate.

Step 2: Navigate to Branding Configuration

In the superadmin sidebar menu, navigate to the Command Center and select the Branding Settings tab. This exposes all active design settings.

Step 3: Upload Logo and Favicon Assets

Under the dynamic assets panel, you can upload custom branding images:

• Platform Logo: Upload your custom SVG or PNG logo (recommended dimensions: 160px by 40px). The dashboard encodes this file to base64 and posts it to /api/v1/superadmin/settings/logo.
• Favicon Icon: Upload your custom browser favicon (ICO, PNG, or SVG format). The dashboard encodes this file to base64 and posts it to /api/v1/superadmin/settings/favicon.

Step 4: Configure Brand Metadata and Primary/Secondary Theme Colors

Customize the dynamic styling variables directly inside the text controls:

• Platform Name: Set your custom brand title (saves as branding_platform_name in the database).
• Primary Color Hex: Set your primary theme highlight (e.g. #6366f1 Indigo, saves as branding_primary_color).
• Secondary Color Hex: Set your secondary layout background (e.g. #F9FAFB, saves as branding_secondary_color).

Step 5: Save and Apply Settings

Click the Save Branding Settings button. All configurations are stored inside the database, and the changes immediately cascade dynamically across all tenant portals, authentication screens, and email headers without requiring a server reboot.

Option 2: Manual Code Configuration

If you prefer updating the files directly inside your repository source code, follow these detailed code replacement guidelines:

Step 1: Replace Default Logo and Identity Files

To change the default logos statically, replace the vector files inside the public asset folder of the frontend project directory:

frontend/public/logo.svg

frontend/public/globe.svg

You can copy your brand images directly over these files using your file manager or standard terminal commands:

# Copy your custom logo SVG over the default logo asset
cp /path/to/your/custom-logo.svg frontend/public/logo.svg

# Copy your custom shortcut icon over the default globe asset
cp /path/to/your/custom-favicon.svg frontend/public/globe.svg

Step 2: Change Default Brand Name and Metadata

Open the branding configuration script in your editor and modify the key metadata values:

frontend/src/config/branding.ts

Update the metadata properties inside the exported BRANDING configuration object:

export const BRANDING = {
  platformName: "CallVIQ", // Change this to your custom SaaS name
  companyName: "CallVIQ Inc.", // Change this to your registered corporate name
  defaultTitle: "CallVIQ", // Change this to your primary page tab heading
  defaultTitleSuffix: " | CallVIQ", // Suffix displayed at the end of browser tabs
  metaDescription: "AI Calling Agent SaaS platform", // SEO search meta description
  testimonialQuote: "CallVIQ replaced our manual customer outreach operations and reduced call handling costs by 80% within the first month.",
  defaultLogoUrl: "/logo.svg", // Target link pointing to your main logo asset
  copyright: "© 2026 CallVIQ Inc.", // Text displayed in the footer of login screens
  byokNotice: "CallVIQ operates on a Bring Your Own Key (BYOK) model. Connect your API keys to support dynamic bot dialogs.",
};

Step 3: Change Color Palette Variables (Tailwind CSS v4)

CallVIQ is styled using Tailwind CSS v4, which defines core configuration parameters inside the root CSS file. Open the global stylesheet to edit variables:

frontend/src/app/globals.css

Locate the :root element and customize the CSS properties to update your application brand colors:

:root {
  /* ... background and layout variables ... */

  /* Change your primary brand color variable here (Hex or HSL color codes) */
  --primary: #0F172A; /* Default charcoal black color for buttons and badges */
  --primary-hover: #1E293B; /* Slightly lighter shade for active hover states */
  --primary-foreground: #FFFFFF; /* Foreground text color inside action buttons */

  /* Change semantic accent status variables if necessary */
  --success: #16A34A; /* Emerald green theme for successful actions */
  --warning: #D97706; /* Warm amber theme for pending notifications */
  --destructive: #DC2626; /* Crimson red theme for deletion processes */
  
  --ring: #0F172A; /* Keyboard navigation focus outline rings */
  --radius: 0.5rem; /* Corner roundness for cards, borders, and input fields */
}

Premium Brand Color Presets

To simplify color selection, you can copy one of our pre-configured color palettes and paste it directly into your globals.css file:

--primary: #4F46E5;
--primary-hover: #4338CA;
--ring: #4F46E5;

--primary: #0D9488;
--primary-hover: #0F766E;
--ring: #0D9488;

--primary: #0284C7;
--primary-hover: #0369A1;
--ring: #0284C7;

--primary: #059669;
--primary-hover: #047857;
--ring: #059669;

1. Download & Unzip the Package

Extract the CallVIQ platform ZIP file from CodeCanyon onto your machine.

The CallVIQ codebase comes in a single ZIP file containing the entire application (both frontend client dashboard and backend api servers). Follow the steps below to extract it:

What the ZIP contains

Once you extract the package, you will see the following files and folders at the root level:

• frontend/ — The merchant client dashboard portal. Built with Next.js 16, React, and Tailwind CSS.
• backend/ — The backend API gateway and sockets pipeline server. Built with Express.js, TypeScript, BullMQ, and mysql2.
• integrations/ — Contains HubSpot CRM cards and projects files configuration to deploy native iframe dashboards inside HubSpot layouts.
• clean_database_schema.sql — The raw database setup schema containing all MySQL table structures, keys, indices, and seeding records.
• documentation.html — The developer manual containing step-by-step setup guides (the guide you are reading now).

How to Unzip

You can extract the ZIP file by right-clicking it and choosing "Extract Here" (or double-clicking on macOS Finder). If you prefer using your terminal, navigate to the folder where you downloaded the file and run:

unzip callviq-codecanyon.zip -d callviq-saas
cd callviq-saas

2. Setup MySQL Database

Create your local MySQL database and import the default tables structure.

CallVIQ uses MySQL to save accounts, billing details, settings, and campaigns. You need to create a new database on your computer and load the schema from the clean_database_schema.sql file.

Step 1: Create the Database

Open your MySQL client or terminal and create a new database. You can name it whatever you like, for example: callviq_db.

mysql -u root -p -e "CREATE DATABASE callviq_db;"

Step 2: Import the SQL File

Import the tables into your database. Run the command below from the root of your unzipped project folder (replace root with your MySQL username):

mysql -u root -p callviq_db < clean_database_schema.sql

Using Database Managers (GUI Tools)

If you don't want to use the terminal, you can easily use graphical database clients instead:

• TablePlus: Open a connection to your MySQL server, right-click, select New Database. Name it. Then go to File ➔ Import ➔ SQL Dump, select clean_database_schema.sql and click Import.
• phpMyAdmin: Select your MySQL server, click the Databases tab, type database name, and click create. Select the database on the left, click the Import tab, browse to choose clean_database_schema.sql, and click Go.
• DBeaver: Right-click your connection, select Create ➔ Database. Right-click the new database, choose Tools ➔ Restore Database, select clean_database_schema.sql, and run.

3. Install Required Packages

Download and install the dependencies for frontend client and backend server directories.

CallVIQ is a full-stack project utilizing a workspace configuration. This means you can install dependencies for both components concurrently with a single command from the project root directory.

Step 1: Check Node.js Version

Ensure that you have Node.js version 18 or newer installed on your computer. You can check by running:

node -v

Step 2: Run Installations

Open your terminal inside the root project directory and execute the commands below. The first command installs general monorepo scripts, and the second command installs the exact NPM libraries needed by both frontend and backend directories:

npm install
npm run install:all

What packages are being installed?

• Frontend libraries: Next.js framework, React components, Tailwind CSS styling, Socket.io-client connections, and Lucide icons dashboard utilities.
• Backend libraries: Express server, Sequelize ORM database engine, BullMQ queues scheduler, Redis client drivers, MySQL2 connectors, and Twilio SDK packages.

4. Set Up Configuration Files

Create your local environment settings (.env files) to connect database and API services.

Both frontend and backend applications require environmental variables to connect to database tables, redis servers, payment gateways, and third-party APIs. We provide template examples to copy and edit easily.

Step 1: Copy Configuration Templates

Run these terminal commands from the root directory to generate active settings files:

cp frontend/.env.example frontend/.env
cp backend/.env.example backend/.env

Step 2: Understand the Settings

Open the new .env files in your code editor (like VS Code or Cursor). Here is exactly what to place in each field:

1. Frontend Configuration (frontend/.env)

2. Backend Configuration (backend/.env)

5. Concurrently Start Local Servers

Launch both the Next.js frontend and Express backend concurrently.

Now that package modules have completed downloading and environmental variables have been initialized, you can boot the servers to start running CallVIQ locally.

Step 1: Launch Servers

Run the developer script command from the root of the project folder. This will automatically execute the dev environments inside both `frontend/` and `backend/` directories at the same time:

npm run dev

Step 2: Accessing Local Ports

Once compilation is complete and logs begin printing to your terminal:

• User Interface: Open your web browser and go to http://localhost:3000 to view the dashboard portal.
• API Server: The REST API backend routes and WebSocket connections will run on http://localhost:5000.

Step 3: Verification Sandbox

To verify the local installation is working completely:

1. Go to the login page: http://localhost:3000/login
2. Click the outline button labeled "Quick Login (Demo)".
3. The form fields will immediately auto-populate, log you in, and redirect you to the main merchant portal dashboard dashboard.
4. Test navigating across sidebar tabs (Campaigns, Dialers, Logs) to ensure everything database related runs successfully.

6. Live Production Deployment

Deploy CallVIQ to a live Ubuntu Linux VPS server for public access.

For a public release, you need to compile the Next.js frontend into static production bundles and run the backend API server 24/7 using PM2 process management behind an Nginx reverse proxy.

Step 1: Install Node.js and PM2

Connect to your server via SSH and install the latest Node.js release, along with PM2 globally to monitor your backend logs:

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

Step 2: Build & Run the Frontend

Navigate to the frontend/ directory, install production packages, compile the Next.js optimization bundle, and launch it using PM2:

cd frontend
npm install --production
npm run build
pm2 start npm --name "callviq-frontend" -- start

Step 3: Run the Backend API

Navigate to the backend/ directory, install production packages, and launch the API server under PM2 supervision:

cd ../backend
npm install --production
pm2 start src/server.js --name "callviq-backend"

Save the PM2 process list so it automatically restarts if the host server reboots:

pm2 save
pm2 startup

Step 4: Nginx Reverse Proxy Setup

Nginx directs public web traffic on ports 80/443 to your active Node.js processes. Install Nginx and configure server blocks:

sudo apt install nginx

Create a configuration file at /etc/nginx/sites-available/callviq to route traffic to the frontend (port 3000) and backend (port 5000):

server {
    listen 80;
    server_name dashboard.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;
    }
}

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

    location / {
        proxy_pass http://localhost:5000;
        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;
    }
}

Enable the site configuration and restart Nginx:

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

Step 5: Setup Let's Encrypt SSL

Secure the public domain endpoints using automatic Let's Encrypt SSL certificates:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d dashboard.yourdomain.com -d api.yourdomain.com

Stripe Payment Setup

Configure Stripe to process customer billing subscriptions and system wallet balances.

CallVIQ uses Stripe as the primary merchant service gateway. Stripe enables credit card processing for tenant subscription upgrades, manual credits wallet top-ups, and automated wallet recharges. Setting up Stripe requires registering API secrets and configuring live webhook listeners on your API server.

Stripe Configuration Details

Stripe integrations rely on two API keys and a webhook signing secret. Complete the following configuration steps to enable payments:

Step 1: Sign up and Choose Mode

Go to Stripe.com and sign up for a merchant account. Once your dashboard is ready, toggling the Test Mode switch in the top right corner allows you to sandbox credit card operations without processing real money. Keep Test Mode enabled during local workspace development checks.

Step 2: Generate Stripe API Keys

Navigate to the Developers ➔ API Keys tab on the left sidebar menu. Copy the primary authentication tokens from this panel:

• Publishable Key: Public identifier token (starts with pk_test_). This key is safe to expose in client browsers.
• Secret Key: Private operational token (starts with sk_test_). Warning: Keep this key highly confidential. Never expose this key in front-end client bundles or repository check-ins.

Step 3: Setup Webhook Endpoint

Navigate to Developers ➔ Webhooks and click Add Endpoint. Set up the webhook targets using these settings:

Once you save the endpoint, click on the webhooks page and reveal the Signing Secret (starts with whsec_). This key verifies that webhook notifications sent to your backend server are authentic Stripe updates.

Step 4: Update Backend Environment Variables

Open your backend settings file and update the Stripe key variables:

backend/.env

Insert your credentials directly into the corresponding variable lines:

# Stripe Integration Credentials
STRIPE_SECRET_KEY=sk_test_51Px...your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=whsec_...your_webhook_signing_secret

Restart your backend server to apply the updated keys. Stripe is now fully connected to handle platform checkouts, monthly billing events, and user credit wallets top-ups.

Google Calendar & Sheets OAuth Setup

Configure Google API credentials to synchronize appointment slots, calendar bookings, agent calendars, and Google Sheets contact imports.

CallVIQ synchronizes agent booking sessions and slot availability indexes directly with Google Calendar, and pulls contact lists from Google Sheets. Setting up these integrations requires generating an OAuth 2.0 Client credentials profile in the Google Cloud Console, and registering the client keys in the system settings database.

Google Integration Details

Google OAuth integrations require a Client ID, a Client Secret, and an Authorized redirect URL callback. Complete the following configuration steps:

Step 1: Create a Google Cloud Project

Go to the Google Cloud Console and log in. Click the project dropdown list in the header bar, select New Project, type in a project name like CallVIQ Integration, and click Create.

Step 2: Enable the Calendar & Sheets APIs

Navigate to the API library and enable Calendar and Sheets resource access:

1. Click the main navigation menu icon and select APIs & Services ➔ Library.
2. Type Google Calendar API into the search box, click on the search result, and click the Enable button.
3. Go back to the library, type Google Sheets API, click on the search result, and click the Enable button.

Step 3: Configure the OAuth Consent Screen

Before generating key credentials, define the platform's OAuth user authorization parameters:

1. Navigate to APIs & Services ➔ OAuth Consent Screen.
2. Select External User Type and click Create.
3. Fill in mandatory metadata inputs: App Name (e.g. CallVIQ Integrations), User Support Email, and Developer Contact Information. Click Save and Continue.
4. Under the Scopes step, click Add or Remove Scopes and add the following required scopes:
   - .../auth/calendar and .../auth/calendar.events (Google Calendar synchronization)
   - .../auth/spreadsheets and .../auth/drive.readonly (Google Sheets lead extraction and contacts imports)
5. Under Test Users, add the Google/Gmail accounts of users you want to allow calendar and sheet sync access during development testing. Click Save and Finish.

Step 4: Create OAuth 2.0 Credentials

Generate Client IDs and secrets to authenticate CallVIQ connection requests:

1. Navigate to APIs & Services ➔ Credentials, click Create Credentials, and select OAuth Client ID.
2. Set Application Type to Web Application and name the client profile.
3. Under Authorized JavaScript origins, add your live frontend dashboard URL: https://dashboard.yourdomain.com (or http://localhost:3000 for local developer testing).
4. Under Authorized redirect URIs, add your callback redirection endpoint URL: https://api.yourdomain.com/api/v1/integrations/google/callback (or local testing url: http://localhost:5005/api/v1/integrations/google/callback).
5. Click Create and copy your new Client ID and Client Secret tokens.

Step 5: Apply Credentials and Enable Integration

Google OAuth credentials are configured via environment variables and enabled globally in the admin portal:

1. Open backend/.env in your code editor and input your Client ID and Client Secret:

   GOOGLE_CALENDAR_CLIENT_ID=your_client_id_here
   GOOGLE_CALENDAR_CLIENT_SECRET=your_client_secret_here

2. Restart your backend server to load the new credentials.
3. Log in to the Super Admin Dashboard and click on the dedicated Integrations tab in the main sidebar.
4. Locate the Google Calendar and Google Sheets cards, ensure the status displays "Configured in .env", and toggle the enablement switches to Active.

Google Calendar integrations are now fully enabled. Tenant dashboard users can now navigate to their profile settings, click "Link Google Calendar", authorize via Google Account Consent, and map system workflows to their Google Calendars.

Email Integration Setup

Configure platform transactional mailing services using custom SMTP parameters or the Resend API.

CallVIQ dispatches transactional notifications (such as verification links, password resets, access invitations, and billing invoices) using an administrative mail provider. The system supports email configurations via standard custom SMTP servers or direct integration with the Resend mailing API.

Option 1: Custom SMTP Configurations

To use an external SMTP mailing provider (like SendGrid, Mailgun, Amazon SES, or private corporate mail servers), follow these configuration steps:

Step 1: Obtain SMTP Connection Settings

Log in to your email delivery service and collect the following parameters:

• Host: The server domain address (e.g. smtp.sendgrid.net or smtp.mailgun.org).
• Port: Secure connection port (usually 465 for SSL or 587 for TLS/STARTTLS).
• Username: Mail API account login credential (e.g. apikey).
• Password: Secure API access password.
• From Email: The authenticated sender address (e.g. noreply@yourdomain.com).

Step 2: Configure in Super Admin Dashboard

Apply the server configuration settings inside the administrator command panel:

1. Log in to the Super Admin Dashboard and navigate to Settings ➔ Mail Settings.
2. Select SMTP as the active mail delivery provider type.
3. Input Host, Port, Username, Password, Sender Name, and authenticated Sender Email. Click Save.

Option 2: Resend API Configuration

If you prefer using the modern Resend API for fast email delivery, complete these setup steps:

Step 1: Generate a Resend API Access Key

Create a verified sender profile and retrieve credentials from the Resend console:

1. Go to Resend.com, log in, navigate to Domains, and complete the DNS TXT record authentication for your email domain.
2. Navigate to API Keys, click Create API Key, grant full sending permissions, and copy the new token (starts with re_).

Step 2: Configure in Super Admin Dashboard

Apply the Resend configuration settings inside the administrator command panel:

1. Log in to the Super Admin Dashboard and navigate to Settings ➔ Mail Settings.
2. Select Resend as the active mail delivery provider type.
3. Input your Resend API Key, Sender Name, and verified Sender Email. Click Save.

Step 3: Dispatch Mail Delivery Tests

To verify that email integration operates successfully, you can run a diagnostic delivery test directly from the Command Center Settings:

1. Under the active Mail Configuration panel, locate the Test Connection section.
2. Type in a valid recipient email address and click the Send Test Email button.
3. Verify that the test dispatch finishes with a success notification status, and check the target email inbox folder to review message formatting.

HubSpot CRM Integration Setup

Connect HubSpot CRM and deploy file-based developer projects for custom app cards inside contact timelines.

CallVIQ V2.0 provides native sync and timeline widgets for HubSpot CRM. You can configure this integration to automatically pull contacts, save call activities, and synchronize lead statuses dynamically. Setting it up requires configuring OAuth redirects and deploying the local project files to your HubSpot developer account.

HubSpot App Registration & Deploy

Step 1: Install the HubSpot CLI

To deploy the custom CRM card to HubSpot, you need to install the HubSpot CLI globally on your machine:

npm install -g @hubspot/cli

Step 2: Initialize & Authenticate CLI

Create a developer account at developers.hubspot.com. Authenticate your CLI using a personal access key:

hs init

This creates a local hubspot.config.yaml file mapping the CLI commands to your developer account ID.

Step 3: Configure Redirect URIs & Scopes

Open the HubSpot configuration metadata file in your editor:

integrations/callviq/src/app/app-hsmeta.json

Ensure the redirect URL matches your public backend domain callback endpoint:

"redirectUrls": [
  "https://api.yourdomain.com/api/v1/integrations/oauth/hubspot/callback"
]

Step 4: Upload and Deploy the Project

From the root folder of the project, navigate to the integrations directory and run the upload command:

cd integrations/callviq
hs project upload

The HubSpot builder compiles the card component iframe assets, registers the scopes (contacts.read/write), and deploys the app directly to your account marketplace sandbox.

Step 5: Configure Credentials and Enable Integration

HubSpot integration credentials must be configured inside your backend environment variables and activated globally in the admin portal:

1. Log in to your HubSpot Developer Console, navigate to Manage Apps, and click Create App.
2. Under the Auth tab, input your Authorized Redirect URI:

   https://api.yourdomain.com/api/v1/integrations/oauth/hubspot/callback

   (For local development testing, use: http://localhost:5005/api/v1/integrations/oauth/hubspot/callback)
3. Under the Scopes tab, check the following permissions:
   • crm.objects.contacts.read & crm.objects.contacts.write
   • crm.objects.deals.read & crm.objects.deals.write
4. Copy the generated Client ID and Client Secret, open your backend/.env file, and save them:

   HUBSPOT_CLIENT_ID=your_hubspot_client_id_here
   HUBSPOT_CLIENT_SECRET=your_hubspot_client_secret_here

5. Restart your backend server.
6. Log in to the Super Admin Dashboard, click on the **Integrations** tab in the main sidebar, select the **HubSpot** card, verify that it displays "Configured in .env", and toggle the switch to Active.

Salesforce CRM Integration Setup

Register Salesforce Connected Apps to capture contacts, synchronize call logs, and update status fields dynamically.

CallVIQ V2.0 supports native Salesforce CRM synchronization. You can configure this integration to capture contact data, record calling sessions directly to Salesforce contact histories, and trigger automated call sequences when lead statuses change. This setup requires registering a Connected App inside your Salesforce developer space.

Salesforce Connected App Registration

Step 1: Create a New Connected App

Log in to your Salesforce Developer Portal. In the top header panel, navigate to Setup. In the left-side search box, type App Manager and select it. Click New Connected App in the upper right corner.

Step 2: Fill App Details & Enable OAuth Settings

Enter the basic metadata fields for your application:

• Connected App Name: CallVIQ CRM Integration
• Contact Email: Your developer email.

Scroll down and check the box to Enable OAuth Settings. Configure these parameters:

• Callback URL: Input the redirection endpoint:

  https://api.yourdomain.com/api/v1/integrations/oauth/salesforce/callback

  (For local testing, use: http://localhost:5005/api/v1/integrations/oauth/salesforce/callback)
• Selected OAuth Scopes: Choose the following scopes:
  - Manage user data via APIs (api)
  - Perform requests on your behalf at any time (refresh_token, offline_access)

Step 3: Save and Retrieve Consumer Credentials

Scroll to the bottom and click Save. (Note: Salesforce takes 2-10 minutes to propagate new Connected Apps). Once saved, click Manage Consumer Details, verify your identity, and copy your **Consumer Key** (Client ID) and **Consumer Secret** (Client Secret).

Step 4: Update Backend Environment Variables

Open your backend/.env configuration file and insert the keys:

SALESFORCE_CLIENT_ID=your_salesforce_consumer_key_here
SALESFORCE_CLIENT_SECRET=your_salesforce_consumer_secret_here

Restart your backend server to apply the changes.

Step 5: Enable Integration in Superadmin Panel

Log in to the Super Admin Dashboard, click on the **Integrations** tab in the main sidebar, select the **Salesforce** card, verify that it displays "Configured in .env", and toggle the switch to Active.

Zoho CRM Integration Setup

Configure Zoho API console client applications to pull contact rosters and sync pipeline deals.

CallVIQ V2.0 provides native synchronization pipelines for Zoho CRM. You can configure this integration to map custom lead lists, import contacts directly to campaign modules, and sync telemetry call recordings with Zoho records. Connecting your Zoho console requires creating a Client ID and Secret in the Zoho Developer Workspace.

Zoho App Console Registration

Step 1: Access Zoho API Console

Log in to the Zoho API Console. Click Add Client and choose Server-based Applications.

Step 2: Create a Server-based Application

Fill in the client configuration settings:

• Client Name: CallVIQ CRM Connector
• Homepage URL: Your main platform homepage domain.
• Authorized Redirect URIs: Enter your backend OAuth callback path:

  https://api.yourdomain.com/api/v1/integrations/oauth/zoho/callback

  (For local development testing, use: http://localhost:5005/api/v1/integrations/oauth/zoho/callback)

Click Create. Zoho will instantly generate your **Client ID** and **Client Secret** credentials.

Step 3: Save Credentials in Backend Environment

Open the backend/.env file in your editor and save the client keys:

ZOHO_CLIENT_ID=your_zoho_client_id_here
ZOHO_CLIENT_SECRET=your_zoho_client_secret_here

Restart your backend server to apply the changes.

Step 4: Enable Zoho CRM Integration

Log in to the Super Admin Dashboard, click on the **Integrations** tab in the main sidebar, select the **Zoho CRM** card, verify that it displays "Configured in .env", and toggle the switch to Active.

Guided Onboarding Wizard (V2.0)

Learn how the Version 2.0 streamlined onboarding wizard configures merchant workspaces, industry profiles, and subscription plans on initial login.

CallVIQ V2.0 features an intuitive, modern multi-step onboarding flow designed to capture business sizing context, map vertical industry use-cases, and activate workspace subscription quotas before launching the main command center dashboard.

Step 1: Account Registration & Email Verification

New merchants register via the platform signup screen (/register) by providing their workspace title, email address, and account password. Upon registration, a multi-tenant tenant record and owner account are provisioned. Email activation tokens are dispatched via system SMTP to verify account ownership.

Step 2: Business Profile & Industry Mapping (/onboarding)

Once authenticated, merchants enter the Version 2.0 Business Profile Configuration step:

• Team Member Size: Select workspace team sizing scale (options: 1 (Just Me), 2 - 10 employees, 11 - 50 employees, 51 - 250 employees, 201 - 500 employees, or 500+ employees).
• Industry Vertical Category: Choose from 12 curated industry categories (Technology, Marketing & Sales, Retail & Commerce, Real Estate, Healthcare, Finance & Banking, Education, Customer Support, Travel & Hospitality, Logistics & Delivery, Legal & Professional, or Other).

Merchants can click Save & Continue to persist profile attributes or click Skip Onboarding to proceed immediately.

Step 3: Subscription Plan & Quota Selection (/onboarding/plans)

Merchants are presented with live subscription plans dynamically managed by the Superadmin:

• Billing Cycle Toggle: Switch seamlessly between Monthly and Yearly billing cycles (with automated 20% yearly discounts).
• Quota Transparency: Inspect exact plan allowances including Minutes/Credits allocation, Max Broadcast Campaigns, Contact Database size, Team Member seats, Concurrency limits, and Integration access.
• Stripe Checkout Integration: Selecting a paid plan initializes a secure Stripe Checkout session (/api/v1/billing/create-checkout-session). Free or trial plans activate instantly.

Step 4: Direct Workspace Dashboard Launch (/dashboard)

Upon plan activation or completion, the database updates onboarding_completed = 1 in the tenants table, and redirects the merchant directly into the main workspace dashboard (/dashboard) with pre-seeded voice agents, telephony management, and CRM pipelines ready for use.

Telephony Carrier Integration

Link your telephony carrier accounts and assign active calling lines across multiple channels.

CallVIQ V2.0 communicates with your leased carrier numbers using low-latency WebSockets (or TwiML/XML call control streams). Placing calls via your direct provider account guarantees complete control over caller IDs, calling lines, and local rates. You can integrate any of the supported channels: Twilio, Telnyx, Plivo, Vonage, or a custom SIP Trunk.

Step 1: Retrieve Carrier Credentials

Log in to your provider's developer console (such as Twilio, Telnyx, Plivo, or Vonage) and copy your authorization credentials:

• Twilio: Account SID & Auth Token.
• Telnyx: API V2 Secret Key.
• Plivo: Auth ID & Auth Token.
• Vonage: API Key & Secret Key.
• SIP Gateway: Registrar URI, Username, and Password.

Step 2: Configure Workspace Carrier Channel

In your tenant dashboard, navigate to Settings ➔ Telephony Integration. Select your active carrier tab, enter the copied credentials, and click Save to bind the gateway profile.

Step 3: Provision Phone Lines

Once credentials are authenticated, select the Numbers management tab. You can lease new geographical/toll-free phone numbers or map your existing pre-configured provider numbers to make them active outbound call sources in your workspace campaigns.

Step 4: Test and Validate Voice Streams

Test calling a sandbox number. The system establishes dynamic WebSocket connections with the media server to execute real-time AI conversations, ensuring bi-directional stream latency is kept below 150ms.

AI Agent Builder & Playground

Configure voice agents, prompt guidelines, and test them in-browser.

The Agent Builder helps merchants customize their AI caller identities. Here you define prompt guidelines, operational boundaries, LLM and TTS voice backends, human handoff triggers, and test conversations in real-time before launch.

Step 1: Create a Custom Agent Profile

Navigate to Agents ➔ Create Agent. Name your caller profile and select an industry vertical (e.g. Sales, Appointment Booking, Support Routing) to populate default system guidelines.

Step 2: Select AI Models, Voice Engines & Carriers

Configure the cognitive, vocal, and network providers for this specific agent:

• AI LLM Provider: Select your LLM backend (e.g. Gemini 2.5-flash, GPT-4o, Claude 3.5, Groq, DeepSeek) and enter model parameters like temperature.
• Voice AI (TTS) Provider: Choose your speech engine (ElevenLabs, Cartesia, OpenAI, Azure, Deepgram, Edge, etc.) and specify the target voice ID.
• Telephony Carrier: Link the agent to Twilio, Telnyx, Plivo, Vonage, or a custom SIP gateway.

Step 3: Setup System Prompts & Human Touch Handoff

Enter the behavioral instructions the agent must follow. In this section, you can also define the **Human Touch** features:

• Human Transfer Number: Set the telephone number to forward the call to when the user requests a human.
• Human Trigger Keywords: Specify words (e.g. human, representative, agent) that immediately trigger call forwarding when spoken by the customer.

Step 4: Simulate Dialogs in the Playground

Click Launch Playground to run browser tests. Grant microphone permissions, select VAD (Voice Activity Detection) thresholds, and talk to your AI agent directly in the browser to refine latencies and prompt instructions.

No-Code Conversational Flow Builder

Map conversational flows with dynamic greetings, branches, and slot bookings.

The Flow Builder lets you map conversational structures visually using a drag-and-drop node graph canvas. Connect question nodes, evaluate user intent answers, schedule calendar slots, and transfer calls to support lines.

Step 1: Open the Flow Editor Canvas

Go to the Agent section and click **Edit Conversational Flow**. You will enter the visual node editor showing standard entry hooks.

Step 2: Define Greeting Triggers

Establish welcoming nodes (e.g. `Greeting Node`). Enter the greeting text the agent says when a customer answers the phone (e.g., "Hi, is this custom name?").

Step 3: Add Conditional Intent Nodes

Drag in intent nodes to branch dialogues based on user answers. Define parameters to check (e.g., if user response confirms appointment availability, route to calendar bookings, otherwise route to call exit).

Step 4: Add Calendar Reservation Nodes

Link slot reservation cards. The node calls connected calendar APIs (like Google Calendar) dynamically, reads open availability slots, suggests dates to the client, and records slot selections.

Step 5: Drag and Configure PSTN Call Transfer (Human Touch) Nodes

To implement live human escalation, drag in a **Transfer Node** (or `transferCallNode`):

• Double-click the node to open settings and configure the **Transfer Number** (e.g. +18005550199).
• Connect edges from frustration triggers, sentiment detection nodes, or direct user help queries to route the call stream instantly to live support.

Step 6: Save and Publish Flow

Click Save Flow to compile and publish the dialog map. The dialer will immediately execute this configuration on all active campaign calls.

CRM & Lead Management

Import lead datasets, map custom variables, and manage list exclusions.

The Lead Management suite helps compile contact databases, map dynamic prompt variables, and filter out do-not-call numbers before campaigns launch.

Step 1: Connect CRM or Upload CSV Spreadsheet

Go to Contacts ➔ Import Contacts. You can compile your database in two ways:

• CRM Direct Sync: Select your connected CRM profile (HubSpot, Salesforce, Zoho, or Google Sheets) and input your source list/spreadsheet identifier to sync leads dynamically.
• Manual Upload: Select a local CSV spreadsheet file and upload it directly.

Step 2: Map Custom Field Columns

Associate your CSV header columns with platform variables. Map phone numbers, names, scheduled slots, and variables to insert inside AI prompts during calls.

Step 3: Define Excluded Contacts

Navigate to the Do Not Call (DNC) list. Enter specific contact numbers manually or upload exclusion lists to block numbers from dialing campaigns automatically.

Step 4: Group Leads into Playlists

Organize contacts into lists (e.g. Q3 Cold Leads, Inbound Inquiries). Link lists to campaign dialers to manage calls targeting target lists.

Campaigns & Dialer Pacing

Start calling campaigns and tune queue workers pacing rates.

Outbound campaigns execute automatic calls utilizing background queues. Tune calling speeds, concurrency limits, and retry intervals to match operational limits.

Step 1: Create a Call Campaign

Go to Campaigns ➔ Create Campaign. Name the campaign, select a target lead list, and associate an AI voice agent.

Step 2: Select Outbound Call Lines

Choose the phone numbers leased in Step 2 to use for outbound dialing. The system will rotate through select caller IDs during queue tasks.

Step 3: Adjust Concurrent calling Limits

Configure concurrency limits (e.g. max 10 concurrent lines). Pacing limits define call frequency to ensure server resources and API connection limits remain stable.

Step 4: Set Retries and Dialing Schedules

Configure call retry counts (e.g. try 3 times if client is busy) and scheduling intervals. Set allowed calling hours (e.g. 9:00 AM to 5:00 PM) to avoid placing calls outside local legal windows.

Step 5: Start and Track Dialing Queues

Click **Launch Campaign**. The background dialer queues calling jobs immediately. Watch dial statuses in real-time, reviewing active, busy, connected, and completed logs.

Audio, Transcripts & Ledgers

Audit call histories, listen to stereos, read transcripts, and inspect cost ledgers.

Every call placed by CallVIQ records dialogue details, audio files, turn-by-turn text dialogs, sentiment outcome tags, and custom transaction costs.

Step 1: Navigate to Call History Log

Go to the **Call Logs** tab in your dashboard. You will see a chronological table listing dialed contacts, durations, and sentiment classifications.

Step 2: Review Dialogue Transcripts

Click on a call record log. The view displays a detailed turn-by-turn transcript (e.g. Caller vs Agent), highlighting customer sentiment changes and intent outcomes.

Step 3: Play Call Audio Recordings

Use the media controls widget on the call log view to stream stereo recordings saved to secure S3 storage. Play, pause, or download audio recordings.

Step 4: Inspect Pricing Ledgers

Check the cost breakdown summary for each call. Inspect the direct carrier connection charge, LLM query token processing fees, and speech generation fees to monitor exact operational expenses.

Stripe Billing & Wallet Management

Configure wallet credits top-ups, transaction logs, and auto-recharge settings.

CallVIQ workspace budgets utilize a virtual wallet system. Manage calling budgets using manual transactions or automated funding rules configured via Stripe.

Step 1: Access Billing Settings

Go to the **Billing** tab in your sidebar. The dashboard shows active plans, current wallet balances, and recent payment lists.

Step 2: Fund Wallet Balance

Click **Add Funds** in the Wallet box. Input the desired funding amount (e.g. $100). The dashboard initiates Stripe Checkout to process the transaction and increment calling credits instantly.

Step 3: Set Auto-Recharge Thresholds

Toggle the **Auto-Recharge** switch. Set a threshold limit (e.g., if wallet drops below $10) and target reload amounts (e.g., purchase $50 automatically). This guarantees dialing campaigns do not pause due to low balances.

Step 4: Download Billing Invoices

Review the transaction history table at the bottom of the page. Click download to fetch PDFs of recent Stripe payments and invoices.

Tenant Directory & Impersonation

Manage tenant workspaces, configure statuses, and impersonate workspaces to troubleshoot setups.

The Tenant Directory is the core admin control panel for supervising active workspaces on your platform. Operators can configure accounts, review limits, and access individual dashboards dynamically.

Step 1: Access Tenant Directory

Go to the Tenants tab in the Super Admin sidebar. The UI dashboard displays a paginated list of all active, suspended, and deleted workspaces.

Step 2: Suspend, Reset, or Modify Tenant Accounts

Select any tenant row to manage active configurations. Click **Suspend Account** to pause calling services instantly, or **Soft Delete** to queue data deletion after 30 days.

Step 3: Secure Impersonation Bridge

Click the **Impersonate** button on a tenant card. The platform securely opens the workspace console as the select merchant. This lets you debug agent builders, test phone connections, and check pricing ledgers without exposing user passwords.

Step 4: Top Up Wallet Balance Manually

Click **Adjust Wallet** in the tenant settings sheet. Enter a credit amount (such as $50.00) to top up their dialer funds manually for testing or customer support balance refunds.

Subscription & Plan Builder

Create custom pricing plan packages, set resource restrictions, and bind Stripe IDs.

Construct subscription pricing packages that control tenant workspace allowances. The plan limits automatically throttle campaigns, contact lists, and API access keys.

Step 1: Create a Pricing Plan

Navigate to Plans ➔ Create Plan in the Super Admin console. Input a plan package name (e.g. Professional Plan) and standard package descriptions.

Step 2: Bind Stripe Pricing Identifiers

Input matching Stripe Price IDs (monthly and annual) in the pricing settings. This links customer subscription checkout pages to automatic Stripe billing webhooks.

Step 3: Define Resource Limits

Set resource caps to constrain operational footprints: adjust max concurrent call channels, total contact list uploads, daily dialing queues, and call recording storage gigabytes.

Step 4: Set Feature Flags and Overage Billing

Toggle premium features (like custom outbound Webhooks or Google Workspace integrations). Define credit overage fees (e.g. $0.05 per call minute) for tenants who exceed included call credit bundles.

White-Labeling & Legal Policies

Configure dynamically white-labeled logos, color themes, titles, and system SMTP routing.

CallVIQ is built for complete multi-tenant white-labeling. Super Admins can customize the visual brand footprints, email senders, and legally binding contract templates directly from the administrator console.

Step 1: Access Branding Panel

Go to the Settings ➔ Branding Settings tab in the Super Admin dashboard to upload brand asset files (Favicons, SVG logos, navbar images) and set primary/secondary brand CSS themes.

Step 2: Define Legal Agreements & Policies

Go to Legal in the admin menu. Use the rich text editors to draft and save your custom **Terms of Service**, **Privacy Policy**, and **DPA Agreements** that tenants must accept when initiating workspace registration.

Step 3: Setup Platform SMTP Senders

Navigate to Settings ➔ Mail Settings to configure platform email delivery triggers. Input your SMTP credentials or verified API gateways (such as Resend or SendGrid) to dispatch verification emails and invoice notifications using your white-labeled brand name.

AI Engine & Voice Providers Setup

Provision default LLM routing configs and activate voice synthesis libraries globally.

Super Admins configure default API keys and enable specific language models to make AI caller capabilities active out-of-the-box for new workspaces prior to personal BYOK configurations.

Step 1: Configure LLM Provider Keys

Navigate to the LLM Settings panel. Enter system-default API keys for the language backends: OpenAI, Google Gemini, Anthropic, or Groq. Toggle the availability state of each model type (e.g. gemini-2.5-pro, gpt-4o-mini) to define which models are visible to merchant workspace managers.

Step 2: Configure Global Voice Providers

Access the Voice Settings dashboard. Connect your master API credentials for speech synthesis platforms, including ElevenLabs, Cartesia, Azure Cognitive Services, Deepgram, or AWS Polly.

Step 3: Manage Global Voice Library

Maintain the system-wide list of default vocal models. You can add public voices, configure parameters (stability, pitch, clarity thresholds), and upload custom cloning vectors (voice files) to make unique branded voice assistants available for customer campaigns.

Global Carrier & Telephony Trunks

Manage system-wide telephony gateways and assign custom SIP trunks.

Super Admins oversee the trunk connections that process call audio traffic across the platform, linking workspaces to multiple carrier systems.

Step 1: Set Master Carrier Credentials

Navigate to the Telephony Settings board. Connect master account credentials for global carriers (Twilio API, Telnyx profiles, Plivo keys, or Vonage trunks) to route standard workspace calling traffic.

Step 2: Setup Generic SIP Trunks

For custom telephony configurations, register your enterprise Session Initiation Protocol (SIP) gateways: input the registrar endpoints, domain tags, proxy ports, and auth configurations to bypass standard carriers.

Step 3: Monitor Trunk Channels

Track simultaneous inbound/outbound channel consumption spikes. The dashboard lists channel loads to assist operators in preemptively scaling carrier line bounds before throttles hit active campaigns.

Integration Controls & Global DNC Compliance

Toggle global workspace integrations and manage blocklists for calling regulatory compliance.

Step 1: Check Integration Status & Toggle Switch

Go to the Integrations panel in the Super Admin dashboard. You can review which third-party plugins (HubSpot, Salesforce, Zoho, Google) are configured in the environment file and toggle individual application switches to **Active** to make them accessible to merchant dashboards.

Step 2: Maintain Global DNC Lists

Navigate to DNC (Do Not Call) in the menu. This board acts as a platform-wide blacklist: input or import lists of restricted phone numbers. The dialer router automatically checks calls against this database and drops outgoing connection attempts to prevent legal compliance violations.

System Health & Queue Diagnostics

Track platform performance metrics, check CPU/RAM usage, and audit BullMQ task queues.

Supervise backend server loads and task worker queues to guarantee maximum platform stability during heavy outbound dialer campaigns.

Step 1: Check KPI Dashboards

Access the main Super Admin screen to monitor overall performance indices. Track monthly recurring revenue metrics, customer count curves, and system call durations.

Step 2: Monitor System Health Dials

Go to the Health dashboard. Review live circular charts listing CPU loads, Memory usage, active Database connections status, Redis cache response latencies, and WebSocket gateway client counts.

Step 3: Audit BullMQ Task Queues

Under Health diagnostics, inspect the Queue Monitor panel. The interface displays active, paused, delayed, and failed dialer jobs executing in the background Redis database.

Step 4: Administer Queue Failures

If queues stall due to network exceptions or credential failures, use the control dashboard: select failed tasks and click **Retry Jobs**, or click **Purge Queue** to prevent system locks.