Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vorel.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
How voice works

When a customer calls your business number, the call flows through: 
Customer phone
    │
    ▼
Telnyx UAE DID  ──►  Telnyx SIP trunk  ──►  Vapi orchestration
                                                 │
                                                 ├─►  Deepgram (STT)
                                                 ├─►  ElevenLabs / Vapi voice (TTS)
                                                 └─►  Vorel custom-LLM proxy
                                                          │
                                                          ▼
                                            Vorel agent (Gemini 2.5 Flash)
                                                  │
                                                  ├─► Router → sub-agent
                                                  ├─► Tool calls (search_offerings, book_appointment, ...)
                                                  ├─► Per-tenant guardrails
                                                  └─► Reply text streamed back through TTS
The agent runs through the same router → sub-agent flow as chat does (qualification / FAQ / booking / handoff), so a customer who calls and later WhatsApps continues the same conversation thread. Customer identity is keyed on phone number, not channel.

​
What the voice agent can do

Bilingual Arabic + English

Detects which language the customer speaks and responds in that language. Mid-call code-switching is supported (customer can mix; agent stays consistent within each turn).

Qualify a new lead

Asks the questions you’d want a human receptionist to ask: name, intent, timeline, contact preference. Captures structured data + writes the lead into your CRM.

Answer questions from your knowledge base

Vector-indexed retrieval against the offerings + FAQ + knowledge entries you’ve populated for your tenant. Answers cite the source.

Book appointments

Finds available slots within your working hours + handoff rules. Books against the local DB today; Google Calendar real-sync ships in Phase 7.

Escalate to your team

On configurable triggers — explicit request, complaint, negotiation, stuck conversation, compliance question. Routes via Slack webhook or email; the conversation lands in your /inbox.

TTS-safe formatting

The agent’s voice replies are formatted for natural speech — no markdown, no URLs, no bullet lists, no parenthetical asides. Channel-aware rules in lib/agents/channel.ts enforce this.

​
Voice quality

Voice quality depends on:
  • Network conditions between the customer’s carrier and Telnyx. International calls (e.g. UAE-mobile to UAE-landline) work cleanly; unusual carrier pairs can have audio quality issues.
  • STT confidence — Deepgram is strong on English, decent on Arabic but accented Arabic varies. Future TODO: per-tenant ASR confidence thresholds.
  • TTS choice — ElevenLabs has higher fidelity; Vapi’s stock voices have lower latency. We default to a balance; per-tenant override is an operator-side change.
We BYO our SIP trunk on Vapi (commit 641da3e, the audio-quality pivot — fixes the asymmetric one-way audio bug that “Telnyx direct import” had on international calls). This gives us full SIP/SDP codec negotiation control, which materially improves audio on UAE cellular calls.

​
Voice billing model

Voice cost per call = Vapi cost (TTS + STT + LLM proxy + transport) + Telnyx cost (per-minute charge) + Gemini cost (LLM tokens used by the agent). We capture every component:
  • Vapi cost ships in the end-of-call-report webhook payload (call.cost + call.costBreakdown); we persist both into billing_events.cost_usd + cost_breakdown.
  • Telnyx cost comes from the daily CDR sync that polls /v2/detail_records and matches by phone number prefix. Lands in billing_events with event_type='telnyx_voice'.
  • Telnyx DID rental is the monthly recurring charge for owning the number; we synthesize one row per (tenant, month) using the rate your operator entered.
  • Gemini tokens are captured in-process via MODEL_PRICES × token counts from the agent dispatch path.
Your operator reviews the per-tenant cost breakdown at /admin/cost-rollup. Until our Stripe billing model lands, your operator generates the monthly invoice from the rollup data + your agreed pricing.

​
Voice quality assurance

Every call is scored after-the-fact by Vorel’s QA pipeline (Phase 8):
  • An LLM scores the call against an 11-criterion rubric (greeting quality, intent capture, tool-call appropriateness, language matching, handoff timing, etc.).
  • Output: a normalized score (0-100), per-criterion breakdown, suggested improvements.
  • Operator-side: stored in qa_evaluations with the conversation transcript; surfaced at /(dashboard)/analytics per-tenant + at /qa operator-side cross-tenant.
Operator can also configure per-tenant guardrails that flag at-runtime:
  • Forbidden phrases: phrases your agent must never use (e.g. clinic-pack ships forbidden_phrases='diagnose'; you can add tenant-specific phrases like “we guarantee” or “best price”).
  • Hallucination thresholds: which v1 + v2 hallucination kinds trigger a Sentry alert. Tighten for high-risk tenants (clinics, regulated verticals); loosen for low-stakes ones.

​
What’s currently NOT supported on voice

  • Voicemail / call-back when busy — if the agent fails (LLM provider outage, network issue), the call disconnects. Phase N-future would add a voicemail-style fallback.
  • Outbound calls — Vorel doesn’t initiate calls TO customers today. Inbound only.
  • Call recording archive — Vapi hosts the recordings; we store the URL reference. Long-term archiving + PII-redacted recordings are deferred features.
  • Conference / multi-party — single-customer-to-agent only.

​
Per-vertical specifics

Each vertical pack tunes the voice agent’s behaviour:
  • Real estate — agent asks about budget, bedrooms, location, viewing preference. Books viewings against your offerings.
  • Salon — agent asks about service preference, time preference, specific stylist. Books appointment slots.
  • Clinic — agent matches symptom keywords to your specialties. Will not diagnose (forbidden_phrases=‘diagnose’ enforced) — escalates anything sounding like medical advice.
  • Restaurant — agent takes reservations, answers menu questions, captures dietary restrictions. Won’t quote prices unless your knowledge base has them indexed.
  • Auto service — agent captures vehicle make/model/year, service request, timing. Books service slots.
  • Generic SMB — agent runs the qualification flow with your custom questions. Most flexible; you pick what to ask.
For per-vertical detail: Real estate · Salon · Clinic · Restaurant · Auto service · Generic.