Appearance
Communications architecture
Read before changing
- This page · 2. ADR-0032 — chat and platform identity (LOCKED) ·
- Communications architecture · 4. Leads and CRM. The machine contract is this page's
context:frontmatter;.claude/rules/domains/chat.mdis GENERATED from it. Gates:test:db·check:rpc·test:ef·check:i18n-keys. Your plan must answer: which principals the conversation is between; whether any address is derived from a phone; whether both tiers still consume the one@qrsetu/domain/chatmodule. Related domains: consumer-biodata · edge-functions · migrations. Machine reads (the manifest'sreads, in order):documentation/portal/communications/index.md·documentation/portal/architecture/adr/0032-chat-and-platform-identity.md.
The single source of truth for how QRSETU talks to people off-app — WhatsApp first, via Meta's official APIs directly, with no third-party WhatsApp platform (WATI, MSG91, or any BSP) as an architectural dependency. The Meta capabilities on these pages were verified against live Meta documentation on 2026-08-21; the governing decision record is ADR-0029.
PARTLY BUILT: THE WHATSAPP OTP PATH AND ITS LEDGER, NOTHING ELSE
This section was written as Phase-0 documentation, before the code. Built since: 20260901120000_v2_communications_whatsapp.sql created the channel-agnostic ledger (communication_messages, communication_message_events) and the WhatsApp registries (whatsapp_business_accounts, whatsapp_phone_numbers, whatsapp_message_templates), all service-role only, and 20260901140000_v2_whatsapp_registry_seed.sql seeded the platform's WABA, its number and three APPROVED qrsetu_otp templates. Two live Edge Functions use them: send-auth-otp sends the sign-in code through the ledger, and whatsapp-webhook applies delivery statuses and records template events without syncing them (QRS-1425). Not built: consent, campaigns, inbound messages, usage rollups, any non-OTP send, and any Admin Hub surface. A diagram here is a design unless its page says otherwise.
Why WhatsApp, and why Meta direct
For QRSETU's India-first audience, WhatsApp is where both sides of every transaction already are — a Ganapati-stall buyer with no app installed and a merchant who lives in chat. The platform's own principles make it the natural rail: anonymous-first (a buyer's phone number is the identity we already hold — orders.buyer_phone is NOT NULL on every order) and proactive, not reactive (a timely "your order is ready" beats any screen the buyer will never open). It also displaces the traditional SMS/DLT dependency this platform has deliberately not taken on.
Direct Meta integration over a BSP because: QRSETU's own WABA needs no App Review (Standard Access as a direct developer), the send/receive/template/analytics APIs are all first-party, a BSP adds a per-message margin and a second system of record, and the one thing BSPs genuinely add — billing convenience (prepaid wallets, invoicing UI) — is a UI concern Meta deliberately keeps out of its API and that an ops runbook covers.
The complete path
What ships when
| Phase | Scope | Why this order |
|---|---|---|
| P1 | transactional UTILITY messages on the money path: order confirmation (buyer + merchant), payment receipt, ready/collected — one WABA, one number, dispatcher + webhook EF + ledger | highest leverage per rupee: the buyer phone already exists on every order, the trigger points are live EFs, utility is cheap and un-capped, and no Meta approval is needed |
| P2 | template lifecycle operations, usage/cost ingest (pricing_analytics), Admin Hub read surfaces, alerts, business verification → the 2,000 tier | operating what P1 created |
| P3 | marketing campaigns on the consent ledger; merchant-facing usage reporting; entitlement-gated merchant campaigns | consent and quality mechanics must exist before the first promotional send |
| P3+ | Tech Provider programme: enterprise tenants with their own WABAs via Embedded Signup; in-chat payments (pending the Razorpay Route question) | separate approval programmes with their own cost |
Section map
| Page | What it answers |
|---|---|
| Meta API assessment | what Meta's APIs actually support — available now vs approval-gated vs unsupported, verified with citations |
| Architecture | the send path, the receive path, retry, Edge Functions, secrets, and how it composes with what exists |
| Flows | per-use-case LLD sequence diagrams: orders, payments, status, signup, templates, campaigns, usage |
| Data model | every proposed table and the reasoning per column, RLS posture, naming |
| Tenant model | can a merchant/enterprise send under their OWN branding, and can QRSETU sell prepaid credits — the three tiers, and why the two goals pull apart |
| Admin Communication Hub | the mission-control surface: nine modules, what Meta can feed each, what stays out |
The three constraints worth carrying in your head
- Meta enforces quality economically. Per-user marketing caps (live in India), template pausing, and tier drops mean the marketing channel degrades under misuse — so the architecture fails closed on consent and never timer-retries into a quality problem. Utility on the money path is the reliable core; marketing is the carefully-rationed edge.
- There is no billing API. Usage and computed cost are readable (
pricing_analytics); payment methods, invoices and any "top-up" concept are Billing Hub UI only. Anything that draws a recharge screen is designing against an API that does not exist. - The INR deadline is real: India-billed WABAs must be INR by 2026-12-31 or delivery stops 2027-01-01. The production WABA is created INR-billed from day one.