# P13 — AI Voice Receptionist: Service Specification

**Status:** Planning · **Updated:** 30 August 2026 · **Owner:** Founder (devs not required)
**Portfolio entry:** `PROJECT_PORTFOLIO.md` → P13 ("opportunistic pilot — anytime (no build)")

> This is a **service** specification, not a product specification. There is no codebase. The "architecture" here is a set of configuration standards, templates and operating rules on rented voice-AI infrastructure. Platform pricing facts were web-verified 30 Aug 2026 (sources in `FOUNDER_GUIDE.md` §8); anything marked **[verify]** must be confirmed on the vendor's own pages before it drives a client quote.

---

## 0. Decisions (settled here so we never re-litigate)

| # | Decision | Rationale |
|---|---|---|
| D1 | **Primary platform: Retell AI. Fallback: Vapi.** | Selection criteria: (a) transparent per-minute pricing we can model ($0.07/min engine, ~$0.10–0.18 all-in **[verify at signup]**); (b) native calendar/booking tools (Cal.com-pattern) so pilots need no middleware; (c) per-second billing + free concurrency + $2/mo numbers; (d) latency/sentiment dashboards good enough to be our QA tooling. Vapi is the fallback and the cost-optimization path (BYO provider keys → ~$0.08–0.10/min budget stack) if Retell pricing or quality shifts. Re-evaluated once, at the P8 gate — not weekly. |
| D2 | **We never build voice infrastructure. Ever.** | The platforms' whole business is sub-second STT→LLM→TTS orchestration. Any hour spent rebuilding it is an hour stolen from the only scarce resource (founder time) to produce a worse result. If a need can't be met by configuration + light glue (n8n/Make/webhooks), it is out of scope. |
| D3 | **No white-label toolkit at pilot stage.** | Synthflow-class reseller toolkits cost ≈ $2,000/mo — 10–20 retained clients of margin. Pilots run under the ThemeTags brand on direct platform accounts. Revisit white-label only past ~15 retained clients. |
| D4 | **The config-template library IS the productization path — designed in from day 1.** | Every pilot's prompts, call flows, tool configs and checklists are written as reusable **vertical templates**, not one-off client files. This is the built-in answer to the binding kill criterion — **delivery time >10h/client/mo (service margin death) → drop or productize config into templates** — the productization isn't a rescue plan, it's the delivery method. Target trajectory: pilot 1 ≈ 25h setup, pilot 3 ≤ 12h, post-template steady state ≤ 8h setup / ≤ 2h/mo care. |
| D5 | **One vertical template first (restaurant), then clone.** | Our restaurant-system client base makes restaurants the warmest pilot pool and we already know their call patterns (hours, menu, reservation, directions). Clinic, salon, real-estate templates are derived clones, one per subsequent pilot. |
| D6 | **Client keeps their number; we attach, never port.** | US: conditional call-forwarding to a platform number. BD/Gulf: WhatsApp Business Calling and/or forwarding designs (`COMPATIBILITY.md`). Porting a business's number into our stack makes us a telecom liability and makes rollback a project. Forwarding rollback is one dial-code — that IS the rollback plan (`DEPLOYMENT.md`). |
| D7 | **Minute caps on every tier; margin floor = infra ≤ 40% of fee.** | Researched all-in cost ~$0.09–0.16/min means an uncapped $99 client can go underwater on infrastructure alone (750 min/mo ≈ $68–120). Caps: $99/250 min, $149/500, $199/800, overage $0.25/min (`PRICING.md`). No unlimited plan exists at any price. |
| D8 | **Escalation-to-human is mandatory in every config.** | Triggers (all four, always): caller asks for a human; caller expresses frustration twice; medical/legal/complaint content; any booking or payment dispute. Action: warm transfer to the designated human line during staffed hours, structured voicemail + instant WhatsApp/SMS alert to owner outside them. A config without a tested escalation path cannot pass `RELEASE_CHECKLIST.md`. |
| D9 | **Recording follows the strictest applicable law per market.** | UAE: all-party consent, criminal penalties → recordings OFF by default, transcript-only QA. US: disclosure line in greeting covers two-party states. BD: disclosure line + consent. Details and the testable checklist: `SECURITY.md`. |
| D10 | **English-first; Bangla and Arabic are gated experiments, not promises.** | Bangla STT/TTS quality at conversational latency is unproven for our use; Arabic is better but untested by us. Neither is sold to a client before passing the 20-call QA script in that language (`COMPATIBILITY.md`). |

---

## 1. What this service is (plain language)

We configure, connect, QA and operate a 24/7 AI phone/WhatsApp receptionist for local SMBs — clinics, salons, restaurants, real-estate offices — on rented voice-AI infrastructure (Retell/Vapi-class). The assistant answers in a natural voice, books appointments into the client's real calendar, captures leads, answers routine questions, and hands anything sensitive to a human. Sold as a managed service at **$99–199/mo including setup**, delivered in ~2 weeks per pilot, entirely by the founder. No product development.

Three markets, one design: **BD** (learning lab, warm agency clients, WhatsApp-first), **Gulf via partners** (WhatsApp-first, all-party-consent constraints), **US via the LLC** (easy telephony, highest willingness to pay, the scale market).

## 2. Service architecture (what exists per client)

| Layer | What it is | Who owns it |
|---|---|---|
| Number & routing | Platform-purchased US number, or WhatsApp Business Calling, + the client's forwarding rules | Platform / Meta; config is ours |
| Assistant config | Voice, language, endpointing/barge-in settings, escalation targets | Ours (from vertical template) |
| Prompt pack | Identity & tone, business knowledge (hours, services, prices, FAQs), booking policy, escalation rules, forbidden topics | Ours — the core IP |
| Tools | Calendar availability + create-booking (Cal.com or Google Calendar), lead-capture webhook → client CRM/Sheet, transfer, SMS/WhatsApp confirmation | Config ours; endpoints standardised in `API_CONTRACT.md` |
| Delivery of results | Booking confirmations, lead alerts, daily call summary, weekly report to client | Ours (platform webhooks → n8n/Make → WhatsApp/email) |
| QA loop | 20-call pre-launch script, week-1 daily review, weekly sampled review | Ours (`TEST_PLAN.md`, `TESTING.md`) |

## 3. Vertical playbooks (the template library, D4/D5)

Each playbook = greeting + knowledge schema + call flows + escalation specifics + QA additions. Status: all ⬜ until built in P2+ (`FEATURES.md`).

### 3.1 Restaurant (template #1 — built first)

| Flow | Behaviour |
|---|---|
| Reservation | Party size → date/time → check availability (calendar/booking tool) → name + phone → confirm + SMS/WhatsApp confirmation. ≤ 8 turns |
| Hours/location/menu Qs | Answer from knowledge pack; offer to send menu link by SMS/WhatsApp |
| Takeaway order intent | v1: capture name/phone/items as a structured message to staff WhatsApp — we do NOT integrate POS at pilot |
| Large party / event / complaint | Escalate (D8) |
| After-hours | Take reservation for future slots; messages for the rest; morning summary to owner |

### 3.2 Clinic (dental/GP-style)

| Flow | Behaviour |
|---|---|
| Appointment booking | Patient status (new/returning) → reason category (from fixed list — never free-form medical advice) → practitioner/slot → book → confirmation |
| Reschedule/cancel | Look up by phone number → modify booking |
| Emergency wording detected | Immediately state emergency guidance line + transfer/redirect — scripted verbatim in the prompt, never improvised |
| Insurance/price questions | Answer only from the approved knowledge pack; else take message |
| Hard rule | No diagnosis, no medical advice, no lab results — forbidden-topics list is part of the template. Health-adjacent PII handling per `SECURITY.md` |

### 3.3 Salon / spa

Booking by service + stylist preference + duration-aware slots; price list Qs; cancellation with fee policy wording; product Qs → message; upsell line ("shall I also book...") only if owner opts in.

### 3.4 Real-estate

Lead capture first (name, phone, budget, area, buy/rent) → CRM webhook; listing Qs from knowledge pack; viewing appointment booking; qualified-lead instant alert to agent's WhatsApp; after-hours is the hero use case (viewings are requested at night).

## 4. Binding metrics (from the portfolio — do not renegotiate mid-pilot)

| Metric | Value |
|---|---|
| Pilot count | 3 pilots from the existing agency network |
| Success | **3 pilots → 2 retained at full price** after the pilot period (P8 gate, `ROADMAP.md`) |
| Delivery time per pilot | ~2 weeks each |
| Kill criterion (verbatim) | **delivery time >10h/client/mo (service margin death) → drop or productize config into templates** |
| Margin floor | Infra ≤ 40% of monthly fee per client (D7) |
| Steady-state labour target | ≤ 2h/client/mo, logged in `PROGRESS.md` |
| QA gate per client | 20-call script passed before go-live (`TEST_PLAN.md`), go-live gate in `RELEASE_CHECKLIST.md` |

## 5. Out of scope (hard constraints)

- Building or hosting any voice/AI infrastructure (D2). No custom code beyond webhook glue.
- Outbound cold-calling campaigns (regulatory minefield, different product; revisit only post-P8 as a separate decision).
- POS/EMR/property-portal deep integrations at pilot (calendar + webhook only).
- Porting client phone numbers (D6).
- Unlimited-minute plans (D7).
- Medical/legal advice by the assistant, payments over the phone, promising "never misses a call" in writing (say "answers 24/7").
- White-label platform spend before ~15 retained clients (D3).

## 6. Open questions for the founder

| # | Question | Blocks |
|---|---|---|
| O1 | Which 3 clients from the network get the pilot offer? (Suggest: 1 restaurant-system client, 1 CRM client, 1 marketing-arm client with heavy phone traffic) | P2/P3 |
| O2 | Pilot billing entity per market: BD clients via ThemeTags (BDT?), US via LLC (USD) — and pilot price: full price from day 1, or discounted month 1? (Recommendation: full price, month 1 refundable — retention at *full price* is the metric) | P3 first invoice |
| O3 | Gulf partner: do we have one warm partner contact to co-pilot a UAE/KSA client in this window, or does Gulf wait for post-P8? | Gulf track only |
| O4 | Approve pilot budget: ≤ $150 total for platform credits + numbers + test minutes across P1–P8 | F-01 |
| O5 | Whose Google Workspace / Cal.com account hosts pilot calendars when the client has no calendar at all? (Recommendation: free Cal.com under client's email, we hold admin during pilot) | C-04 |
| O6 | Recording policy sign-off per market per D9 — founder reads `SECURITY.md` §2 and initials the per-market defaults before pilot 1 goes live | Go-live gate |