Knowledge > Runbooks > Voice Operations
Voice Operations Runbooks
Operational procedures for managing the ChurchWiseAI voice agent — provisioning new churches, debugging call issues, deploying code changes, and handling platform outages.
Architecture Summary
The voice agent is a multi-tenant LiveKit Agents v1.5 deployment. ONE agent instance serves ALL churches. Routing happens in session.py:resolve_route() — the inbound phone number is looked up in the PHONE_REGISTRY dict and church_voice_agents Supabase table to load the correct church config. No redeploy is needed when adding a new church.
- Code:
C:\dev\churchwiseai-web\voice-agent-livekit\ - Deploy:
C:\dev\lk.exe agent deploy --project cwa-voice --silent(from thevoice-agent-livekit/directory) - Hosting: LiveKit Cloud — project
cwa-voice-9x077mph - LLMs: Gemini 2.5 Flash (primary), Claude Haiku 4.5 (Care Agent + fallback)
- Phone routing: Telnyx (new customers) + Twilio legacy numbers, both via SIP trunk to LiveKit
Runbooks
| Runbook | When to Use |
|---|---|
| add-voice-agent.md | Provision a new church on the voice agent |
| voice-agent-debug.md | Debug a misbehaving call or routing failure |
| voice-agent-update.md | Deploy code changes to the voice agent |
| handle-missed-calls.md | Review and action missed call notifications |
| prayer-request-follow-up.md | Process prayer requests received via voice |
| voice-call-quality-review.md | Review call quality and tune agent performance |
| cartesia-outage.md | Respond to a Cartesia platform outage |
Key Tables
| Table | Purpose |
|---|---|
church_voice_agents | Per-church config (phone, greeting, prompt override) |
voice_call_logs | All call transcripts, recordings, Gemini classification |
voice_prayer_requests | Prayer requests (voice + chatbot — shared table) |
voice_callback_requests | Callback requests (voice + chatbot — shared table) |
voice_visitor_contacts | Visitor captures (voice + chatbot — shared table) |
Safety Rules
- NEVER modify the main LiveKit SIP trunk (
ST_Xa3Bp9aixRFP) — only the voice-agent-engineer may touch it. An agent broke all Twilio lines by changing the + prefix. - Do NOT redeploy just to add a new church — update the DB row instead.
- New customer phone lines use Telnyx; legacy lines use Twilio. Both route via SIP to LiveKit.
- Deploy command must be run from the
voice-agent-livekit/directory.
See Also
- deploy-voice-agent.md — deployment runbook
- Voice agent architecture