VoiceDesk AI — Voice Receptionist Dashboard & Agent System

An advanced, production-ready AI Voice Receptionist system capable of handling inbound/outbound Webrtc & SIP telephone calls, real-time department routing, dynamic knowledge base parsing (RAG), and appointment bookings (supporting both Google Calendar and Cal.com).

The system consists of two primary layers:

1. The PHP Dashboard (Frontend/Client Admin): Typically deployed on standard shared hosting (e.g., Hostinger).
2. The Python Backend Services: Composed of a FastAPI Gateway (agent_api.py) and a LiveKit Agent Worker (agent.py) which must run 24/7 on a VPS or dedicated cloud instance.

---

🏗️ System Architecture

graph TD
    ClientBrowser[Client Web Portal] -->|HTTP Request| HostingerShared[Hostinger PHP Backend]
    HostingerShared -->|MySQL| Database[(MySQL Database)]
    HostingerShared -->|POST /calls/trigger| FastAPIGateway[FastAPI Gateway :8000]
    FastAPIGateway -->|Dispatch Job| LiveKitCloud[LiveKit Cloud Signaling]
    LiveKitCloud -->|Triggers Worker| AgentWorker[LiveKit Agent Worker]
    AgentWorker -->|WebRTC Audio Loop| UserPhone[User Device / SIP Caller]
    AgentWorker -->|Direct API| GoogleCalendar[Google Calendar API]
    AgentWorker -->|Direct API| CalCom[Cal.com API]

Loading

---

🛠️ Requirements & Prerequisites

1. External APIs & WebRTC Cloud

• LiveKit Cloud: Sign up at LiveKit Cloud to get your WebRTC credentials and token secrets.
• Speech & LLM Providers: API keys from Deepgram (STT/TTS) and Groq (best-in-class low-latency LLMs).
• Google Cloud Platform (Optional): A free Google OAuth client for click-based Google Calendar connection. Redirect URI: https://voice.orangeweb.io/google/callback.
• Cal.com (Optional): A developer API key and event type IDs/slugs.

2. Hosting Environments

• Shared Hosting (e.g. Hostinger): For hosting the PHP dashboard frontend files (hostinger_dashboard/).
• VPS / Cloud Instance (e.g. Hostinger VPS, DigitalOcean, AWS): Running Ubuntu/Linux for hosting the Python backend services (agent.py and agent_api.py) 24/7.

---

🚀 Deployment Guide

Part 1: Deploying the PHP Dashboard (Shared Hosting)

1. Upload the entire hostinger_dashboard/ directory to the public_html/ root (or a folder like /Voice/LIvekitAIVoice) of your Hostinger shared hosting account.
2. In Hostinger hPanel, create a new MySQL Database.
3. Import the schema.sql database file to initialize the tables (agent_configs, call_logs, invoices, etc.).
4. Update hostinger_dashboard/api/config.php with your MySQL database credentials and set the AGENT_API_URL to point to your VPS (e.g., http://your-vps-ip:8000).

---

Part 2: Deploying the Python Agent 24/7 (VPS Server)

The Python backend contains:

• FastAPI Server (agent_api.py): Receives POST trigger requests from PHP and communicates with LiveKit APIs.
• Agent Worker (agent.py): Connects persistently to LiveKit cloud over WebSockets, waits for dispatched calls, and runs WebRTC audio streams.

1. Setup the Environment on your VPS

Log into your VPS via SSH and execute the following commands:

# Update packages
sudo apt update && sudo apt upgrade -y

# Install Python 3.10 and Virtual Environment tools
sudo apt install python3-pip python3-venv python3-dev build-essential -y

# Navigate to your project directory
cd /var/www/voicedesk-agent

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install required packages
pip install --upgrade pip
pip install -r requirements.txt

2. Configure Environment Variables

Create a .env file in the root directory:

LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_livekit_key
LIVEKIT_API_SECRET=your_livekit_secret

DEEPGRAM_API_KEY=your_deepgram_key
GROQ_API_KEY=your_groq_key
LLM_PROVIDER=groq
GROQ_MODEL=llama-3.3-70b-versatile

# Calendar Defaults (cal.com fallback)
CAL_API_KEY=cal_live_xxxx
CAL_EVENT_TYPE_ID=5570683

3. Run the Services 24/7 (Production Configuration)

To ensure the services do not stop when you close your SSH terminal, use PM2 (Process Manager 2) or systemd service units.

Option A: Using PM2 (Recommended & Easiest)

1. Install Node.js & PM2 on the VPS:

   sudo apt install nodejs npm -y
   sudo npm install pm2 -g

2. Create a PM2 ecosystem file (ecosystem.config.js) in your project root:

   module.exports = {
     apps: [
       {
         name: "voicedesk-api",
         script: "./venv/bin/python",
         args: "-m uvicorn agent_api:app --host 0.0.0.0 --port 8000",
         cwd: "/var/www/voicedesk-agent",
         watch: false,
         env: {
           PORT: 8000
         }
       },
       {
         name: "voicedesk-worker",
         script: "./venv/bin/python",
         args: "-u agent.py start",
         cwd: "/var/www/voicedesk-agent",
         watch: false
       }
     ]
   };

3. Start both services:

   pm2 start ecosystem.config.js

4. Save the PM2 list and configure it to boot automatically on VPS restarts:

   pm2 save
   pm2 startup

Option B: Using systemd Services

Alternatively, you can write native Linux systemd service files:

Create /etc/systemd/system/voicedesk-worker.service:

[Unit]
Description=VoiceDesk LiveKit Agent Worker
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/var/www/voicedesk-agent
ExecStart=/var/www/voicedesk-agent/venv/bin/python -u agent.py start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Create /etc/systemd/system/voicedesk-api.service:

[Unit]
Description=VoiceDesk FastAPI Gateway
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/var/www/voicedesk-agent
ExecStart=/var/www/voicedesk-agent/venv/bin/python -m uvicorn agent_api:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start the services:

sudo systemctl daemon-reload
sudo systemctl enable voicedesk-worker voicedesk-api
sudo systemctl start voicedesk-worker voicedesk-api

---

🔧 Troubleshooting Guide

• Verify API Ports: Check if the FastAPI port 8000 is open on your VPS firewall (e.g. sudo ufw allow 8000/tcp).
• Check PM2 Logs: run pm2 logs to see real-time stdout and stderr output.
• Worker Connectivity: If you get a DNS resolution failed or getaddrinfo failed warning, verify that your VPS has active internet access and can resolve your LIVEKIT_URL host domain.