OpenAI / AI Engine

KaiVox uses OpenAI GPT-4o as its AI brain — handling all voice conversations, intent detection, sentiment analysis, and fallback responses. One platform-level API key serves all tenants.

Environment Variable

OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

ConversationEngine — How It Works

App\Services\ConversationEngine is the central AI handler. It is called by both VobizService and TwilioService on every speech input from a caller.

Processing Pipeline

1. Build system prompt The engine assembles a multi-part system prompt:

   • AI persona from the tenant's ai_persona settings (name, voice style, language)
   • Industry pack prompt from industry_vertical_packs table (if tenant has selected a pack)
   • Local intelligence context from LocalIntelligenceService::buildAiContext() — current holidays, weather disruptions, seasonal context, cultural greetings
   • Knowledge Brain context from KnowledgeService::buildAiContext() — up to 8 FAQ/SOP/pricing items, max 3000 chars
2. Intent detection Before sending to OpenAI, IntentRouter::detect() runs a keyword scan on the caller's speech. Detected intents: emergency, speak_to_human, complaint, book_appointment, cancel_appointment, hours, pricing, location, general.
3. OpenAI API call The conversation history (system prompt + all previous turns) is sent to gpt-4o via a Guzzle HTTP POST to https://api.openai.com/v1/chat/completions. The response text is extracted and returned.
4. Emergency escalation check If intent is emergency or speak_to_human, the engine creates an EscalationQueue record and adds escalation instructions to the AI response.
5. Log the AI action Every significant event (intent detected, response generated, escalation triggered, failover activated) is logged via AiActionLog::record() to the ai_action_logs table.

System Prompt Structure

You are Aria, the AI receptionist for Pragati Women's Hospital.
Speak in a warm, professional, and caring tone.
Always respond in English. Keep responses under 3 sentences.

BUSINESS CONTEXT:
Industry: Healthcare (Medical)
Working hours: Mon-Sat 9am-7pm, Sunday closed.
Emergency line: Call 102 for ambulance. For emergencies say: "Please call 102 immediately."
Doctors available: Dr. Meera Patel (Gynecology), Dr. Anita Shah (Obstetrics).

LOCAL CONTEXT:
Today is Saturday, 9 Aug 2026. Time in Asia/Kolkata: 10:30 AM.
Upcoming holiday: Independence Day (15 Aug) — clinic will be closed.
Season: Monsoon. Mention that the clinic is easily accessible via covered parking.

KNOWLEDGE BASE:
[FAQ] Appointment booking: Call us or use the app to book. Same-day slots available Mon-Fri.
[PRICING] Consultation fee: Dr. Patel ₹500, Dr. Shah ₹600. Ultrasound ₹800.
[POLICY] Cancellation: Please cancel at least 2 hours before your appointment.

Intent Detection

App\Services\IntentRouter uses keyword matching (no extra API call) to classify the caller's intent before OpenAI processes it.

Sentiment Analysis

After a call ends, KaiVox runs a second OpenAI call to analyse the full conversation transcript. The result is stored on the call_logs record.

A negative sentiment on a call triggers the call_negative_sentiment automation trigger — which can fire automations like notifying the owner or moving the customer to a complaint pipeline stage.

Failover System

Every OpenAI call is wrapped in FailoverService::withFallback(). If OpenAI throws an exception (timeout, rate limit, 500 error), the failover system:

1. Catches the exception
2. Logs a failover_activated event in ai_action_logs
3. Returns an intent-aware fallback response (not a generic error)

emergency      → "This sounds urgent. Please call emergency services at 102 immediately."
book_appointment → "I'm having a brief technical issue. Please call back in a moment to book."
speak_to_human → "Let me connect you to our team. Please hold."
general        → "I'm sorry, I didn't quite catch that. Could you please repeat your question?"

AI Persona Editor

Each tenant can customise their AI persona at Settings → AI Persona:

• Name — e.g. "Aria", "Kai", "Max"
• Voice style — professional, friendly, formal, casual
• Language — English (Indian), English (US), Hindi (future)
• Greeting message — first thing the AI says on answering
• Escalation message — what AI says when transferring to a human

AI Prompt Versioning

Prompt changes are tracked in the ai_prompt_versions table. Super Admins can view and revert to any previous version via Super Admin → AI Prompts. Tenants can A/B test prompts via Settings → Voice A/B Testing.

Troubleshooting OpenAI