One door for every message

Every WhatsApp message — inbound from customers, outbound from any agent or staff member — passes through a single gateway. One door means one place to record, one place to enforce safety, and one place where a mistake can be stopped before it costs money or reaches the wrong person.

flowchart LR
    subgraph IN["Inbound"]
      META1["Meta / WhatsApp"] --> REC["Recorder
saved BEFORE anything else"]
      REC --> BELL["🔔 Doorbell
wakes marriageAI"]
    end
    subgraph OUT["Outbound — the send door"]
      MAI["marriageAI"] --> DOOR
      OAI["outreachAI"] --> DOOR
      STAFF["Agent Inbox (staff)"] --> DOOR
      DOOR["POST /api/v1/send
internal token required"]
      DOOR --> DUP{"Duplicate?"}
      DUP -->|"yes"| SKIP["skipped —
idempotent by design"]
      DUP --> BAND{"Test-band
number?"}
      BAND -->|"registered 8880…"| SIM["🧪 diverted to simulator —
free, never reaches Meta"]
      BAND -->|"unregistered 8880…"| REFUSE["🛑 refused outright"]
      BAND -->|"real customer"| META2["Meta / WhatsApp"]
    end
    classDef hi fill:#e7f6f1,stroke:#0e8a72,color:#182420
    class REC,DOOR hi
    

Why "record first" matters

The inbound recorder saves every customer message before acknowledging it to Meta. If anything downstream crashes, the message is already safe — nothing a customer says can be lost to a bad moment in another service.

Why one send door matters

• Idempotency — the same message can't be sent twice by a retry; the gateway remembers what it has already delivered.
• A single ledger — every outbound message is recorded in one place, with who sent it and why.
• Window rules in one place — WhatsApp's 24-hour free-messaging window is enforced by expiry timestamp, never by cached flags that can go stale.
• Templates must name their language — a template send without an explicit language is rejected rather than silently defaulting to English against an Urdu template.

The test band that cannot leak

Numbers starting 8880 belong to a reserved international band that no real customer can own. Registered test numbers are diverted to the simulator — the full pipeline runs, nothing reaches Meta, nothing costs anything. Unregistered band numbers are refused at the door (this closed a real gap: one unregistered test number had previously slipped through and been billed). Test traffic is also excluded from the daily sending quota, so testing never eats production capacity.