Skip to main content

Pastor onboards Voice Agent

Persona​

A small-church pastor who just paid for Starter Voice ($49.95/mo). Comfortable with web forms but not APIs. Wants setup in under 10 minutes. Decision fatigue is high — they expect a wizard, not a blank form.

Entry points​

  • Welcome email (Email 1 of 2) — fires immediately after Stripe webhook processes payment. Subject: "Your Voice Line is Being Set Up". Contains magic link button and estimated 1-business-day timeline.
  • Confirmation page — /onboard/return shows "Go to Your Dashboard" linking to /admin/[token].
  • Stripe Customer Portal — subscription view may include a management link.

Click-through flow​

Steps​

  1. Receives welcome email — Clicks magic link. Token generated during provisioning, stored in premium_churches.admin_token, points to /admin/[token].

  2. Lands on dashboard — Onboarding wizard auto-opens if church is in pending_setup state. Calls, Requests, Settings, and Training tabs visible (Training read-only for Starter).

  3. Step 1 — Church profile confirmation — Read-only display of church name, denomination, service times. No DB write; confirms data already in premium_churches and organization_settings.

  4. Step 2 — Configure voice greeting — 150/300 char field with example placeholder. "Preview" button plays a TTS sample. Saved to church_voice_agents.welcome_greeting. At call initialization, session.py injects this into Coordinator instructions.

  5. Step 3 — Set business hours — Day/time picker with presets ("9am–5pm weekdays", "24/7"). Stored in organization_settings.business_hours as JSON. Voice agent can reference hours mid-call.

  6. Step 4 — Escalation contact — Required email (and optional phone) for urgent calls. Saved to church_voice_agents.escalation_contact_email. Crisis detection fires immediate alert to this address.

  7. Provisioning check — If provisioning is still running, Calls tab shows "pending...". Client polls /api/admin/voice-status?token=[token] every 10 seconds. Most provisioning completes in 1–2 minutes; can take up to 1 business day if Telnyx number availability is limited.

  8. Voice Line Live email and test call — When provisioning completes, Email 2 fires with assigned number and carrier-specific call-forwarding instructions. Pastor forwards their existing number or gives out the Telnyx number directly. Test call confirms greeting plays and transcript appears in Calls tab.

Acceptance spec​

Canonical: knowledge/acceptance/starter-voice.md (62 touchpoints, COMPLETE).

FeatureStarter VoicePro VoicePro Both
Voice agents2 (Care + Coordinator)22
Chatbot——Yes (4 agents)
FAQsHiddenVisible (50 limit)Visible (50 limit)
Analytics——Yes

Success criteria​

  1. Magic link works on first click.
  2. Wizard completes in under 10 minutes.
  3. Greeting and hours save without "pending" delays during wizard.
  4. Escalation email receives a test alert within seconds of a crisis call.
  5. Phone number visible in dashboard before "Voice Line Live" email.
  6. Test call transcribed correctly in Calls tab.

Known failure modes​

  • Magic link invalid. Token generated in provision.ts:generateAdminToken() — must be 32+ char hex. Verify token is stored in premium_churches.admin_token at pre-checkout time.

  • Greeting not read at call time. If session.py:load_church_data() times out or races, agent falls back to hardcoded default. Ensure church data fetch awaits before building Coordinator prompt.

  • Provisioning hangs. Telnyx or LiveKit SIP creation failure enqueues to retry inbox (exponential backoff). After 10 failed retries, moves to abandoned and fires P0 alert to founder_action_items.

  • Invalid business hours format. Wizard must validate HH:MM on blur before saving. Invalid JSON in organization_settings.business_hours causes agent time checks to throw at call time.

  • Crisis safety net not triggered. safety.py:detect_crisis() must run deterministically on every response before TTS streams. See voice-agent-livekit/safety.py lines 40–80. Disabling it is a P0 incident.