# P13 — Integration Runbook Standards

**Updated:** 30 August 2026 · This replaces a code API contract: P13 ships no code, but every client integration follows these fixed patterns so any configuration is legible to anyone on the team and portable across platforms (D1 fallback insurance). Deviating from a pattern requires a note in `PROGRESS.md` decisions log.

---

## 1. The standard client integration set

Every client gets exactly these four integration points — no more at pilot stage (`SPEC.md` §5):

```
                    ┌────────────────────────────────────────┐
 Caller ⇄ Platform  │ ① Calendar tool (availability + book)  │ → client calendar
        assistant → │ ② Lead webhook                         │ → client CRM / Sheet
                    │ ③ Call-ended webhook                   │ → summaries & alerts
                    │ ④ Transfer target                      │ → owner's phone
                    └────────────────────────────────────────┘
```

## 2. Calendar hookup patterns (pattern ①)

Preference order, and why:

| Priority | Pattern | When | How |
|---|---|---|---|
| 1 | **Platform-native calendar tool** (e.g. Retell/Vapi built-in Cal.com or Google Calendar tools) | Client has Google Calendar or none (we create free Cal.com per O5) | Configure the platform's own availability-check + create-booking tools; zero middleware to maintain |
| 2 | **Cal.com API via n8n/Make** | Client on Calendly/Outlook or needs custom rules (buffers, staff routing) | Assistant tool → webhook → n8n flow → Cal.com `GET /slots` + `POST /bookings` (API-key auth); Cal.com syncs onward to Google/Outlook |
| 3 | Direct Google Calendar API middleware | Only if 1 and 2 both fail | Last resort; document why in the client runbook |

Standards regardless of pattern: bookings carry caller name + phone + service in the event body · a failed booking NEVER ends the call silently — assistant falls back to "I'll have [owner] confirm by message" + message capture · timezone pinned to the business's locale in one place · confirmation to the caller by SMS (US) or WhatsApp (BD/Gulf).

## 3. CRM webhook patterns (pattern ② — lead capture)

Standard lead payload (JSON, same keys for every client — the template flows emit exactly this):

```json
{
  "client_id": "salon-mirpur-01",
  "call_id": "platform-call-id",
  "captured_at": "2026-09-14T19:42:00+06:00",
  "channel": "phone | whatsapp",
  "caller_name": "…", "caller_phone": "…",
  "intent": "booking | inquiry | complaint | other",
  "vertical_fields": { "service": "…", "budget": "…", "area": "…" },
  "summary": "two-sentence plain-language summary",
  "transcript_url": "platform link (auth-gated)"
}
```

Destinations, preference order: client's CRM webhook endpoint (trivial when it's our own CRM build) → Google Sheet via n8n (clients with no CRM) → email-only (last resort, discouraged — no follow-up tracking). Delivery rule: instant for `intent: booking|complaint`, batched daily otherwise. Retry ×3 with backoff; a dead webhook alerts US (founder WhatsApp), never fails silently.

## 4. Recording / transcript delivery to client (pattern ③)

| Item | Standard |
|---|---|
| Daily summary | 1 WhatsApp/email message per day per client: calls answered, bookings made, leads captured, messages needing action. Generated from call-ended webhooks via one shared n8n flow parameterized per client — never one bespoke flow per client |
| Transcripts | Available on request + linked in lead payloads; access via the platform dashboard's client-scoped view where supported, else we export |
| Audio recordings | ONLY where market policy allows (`SECURITY.md` §2 — UAE: no audio). Delivered via expiring links, never as email attachments |
| Weekly report | Growth/Pro tiers: minutes used vs cap, containment %, bookings, top unanswered questions (which feed prompt updates, task `C-22`) |

## 5. Credentials & config hygiene (summary — full rules in `SECURITY.md` §3)

One platform sub-organization/workspace per client where the platform supports it · client credentials (calendar OAuth, CRM keys) stored in the team vault, named `p13/<client_id>/<system>` · no credentials in prompt text, ever · every client has a runbook file (`clients/<client_id>/RUNBOOK.md`, from the template in `DEPLOYMENT.md` §5) recording: numbers, forwarding codes, tool endpoints, webhook URLs, escalation targets, QA sheet link.

## 6. Portability rule (the D1 insurance)

Prompts, call-flow definitions, knowledge packs and this payload schema are maintained in **our** template repo folder (plain markdown/JSON), then pasted/synced into the platform — never authored only inside the platform's UI. If Retell dies or triples its prices tomorrow, re-standing a client on Vapi is configuration labour (est. 4–6h/client), not a rewrite.