How Oshun's AI-powered med spa system works, end to end
Patients message on WhatsApp, Instagram, the website, or call the clinic. Karen replies, books appointments, sends pre-care and post-care follow-ups, chases payments, and posts to social media — automatically, 24/7.
If you want to see the moving parts, change Karen's behavior, add a procedure, or understand why something happened — this is the map. No coding required to read it; editing some things does need Matthew.
System Layers (below) = the parts of the machine. The 10 Journeys = what happens for a patient or a campaign, step by step. Click any tab to expand.
How a message moves through Oshun's system, left to right.
A patient message lands on any channel → Karen reads context and decides → she takes an action → everything is saved to memory. You can intervene at any point via Telegram.
Most common adjustments and who owns them.
Tone, phrasing, pricing answers, booking hours, procedure descriptions.
How: tell Karen in Telegram — "Karen, update your pricing for Botox to $X." She stores it in memory immediately. No deploy needed.
Owner: Matthew or Dr. Rockhead via Telegram
Add a new pre-care guide, adjust the 24h/1-week/4-week check-in timing, change the review request wording.
How: edit the care-plan JSON for that procedure (Matthew handles). Ask Karen in Telegram to show the current plan first.
Owner: Matthew (code) · approved by Dr. Rockhead
New procedure type, new phone line, new Instagram account, new email list.
How: channel/integration changes are a config + deploy job. See the matching layer below — each panel shows the file that controls it.
Owner: Matthew
Stop a campaign mid-send, pause Karen for one patient, escalate a complaint to Dr. Rockhead.
How: ask Karen in Telegram. Examples: "Karen, pause the broadcast." / "Karen, hand off the Jane Smith conversation to Dr. Rockhead."
Owner: anyone with Telegram access
Each layer is a part of the machine. Click a tab to see what it does and which file controls it.
Messages arrive via WhatsApp Business API, routed through Chatwoot to Karen AI.
Oshun's primary patient channel. Phone: 18766766297. ~14s response time.
Chatwoot component →Instagram DMs routed through Chatwoot to Karen AI.
Connected via Chatwoot Cloud account 156369. Karen replies in ~14 seconds.
Chatwoot component →Operator control channel for Matthew and Dr. Rockhead — not patients.
Content approval, alerts, procedure marking, billing control, system commands.
Telegram component →Inbound calls to (876) 676-6297 hit Twilio SIP trunk → ElevenLabs voice agent.
Patients talk to Karen — real-time voice AI. Books appointments, answers questions, escalates.
Voice / Twilio component →Bulk campaigns via Listmonk. 5K email list + 43K phone contacts.
SMTP: karen@oshunja.com. 6 HTML templates. Campaign 1 sent, 2 & 3 in draft.
Listmonk component →Website chat widget powered by Chatwoot.
Embedded on oshunja.com. Conversations thread with WhatsApp/IG — same contact, same history.
Chatwoot component →Omnichannel inbox — WhatsApp, Instagram, website widget all funnel here.
Cloud account 156369. Manages conversation threading, contact merging, webhook dispatch to Karen AI. Also serves as CRM.
src/webhooks/chatwoot.js → registerChatwootRoutes()Bot wiring — slash commands, inline buttons, media handling.
Handles operator messages, dispatches to AI or direct action handlers. 7 domain handler files in telegram_actions/.
src/telegram.js → startTelegramBot()SIP trunk routing inbound calls to ElevenLabs voice agent.
Twilio handles phone infrastructure. ElevenLabs provides real-time TTS/STT. Karen's brain processes the conversation.
src/webhooks/voice.js → voice routesSelf-hosted email marketing — campaigns, subscriber lists, delivery analytics.
SMTP via oshunja.com or Gmail fallback. Handles unsubscribes automatically. Data sovereignty — no third-party routing.
src/consolidator_briefings.jsThe central intelligence — orchestrates all conversations across every channel.
OpenRouter for chat, Gemini for cheaper tasks. Forward-Thinking Protocol: acknowledge → connect to goals → actionable next step. Action tag system dispatches real actions.
src/ai.js → chat() (line 125)pgvector semantic search + knowledge storage. Karen remembers everything.
Hybrid search: vector similarity + full-text + tags + exact match, combined via RRF fusion. Per-turn consolidation extracts facts automatically.
src/memory.js → hybridSearch() (line 125)Gathers everything Karen needs to respond — history, contact profile, relevant knowledge.
Queries: recent conversations, contact preferences, memory knowledge, tenant persona, core memory sections.
src/context-builder.js → buildContext() (line 20)Assembles the system prompt with persona, available actions, and protocol instructions.
selectActionsForContext() filters which actions Karen can take based on channel and tenant tier. Bakes in Forward-Thinking Protocol.
src/prompt-builder.js → buildDefaultPrompt() (line 217)Cal.com appointment booking with webhook-driven lifecycle.
Patients book at cosmetic.oshunja.com/booking. Webhooks trigger care plans — pre-care, reminders, post-care all start from a booking.
src/actions/calendar.jsAutomated pre-care and post-care sequences for every procedure.
6 pre-care guides approved (Laser, Botox, Fillers, Weight Loss, Lipo, PRP). Check-ins at 24h, 1 week, 4 weeks. Escalation on patient concerns.
src/actions/care/plans.js → startCarePlan()Daily AI content generation → Telegram approval → multi-platform posting.
7 AM EST daily pipeline. Brand-aware generation. Blotato publishes to IG, FB, YT. Engagement scoring feeds next cycle.
src/consolidator_content.js → runDailyContentPipeline()PayPal integration with 6-hop payment state machine.
awaiting → grace → staff_prompted → patient_prompted → at_risk → reconciliation → complete. 10% commission tracking. Escalation: day 3/7/14/30.
src/webhooks/billing.js → registerBillingRoutes()Blotato API — multi-platform publishing to Instagram, Facebook, YouTube.
Handles caption formatting per platform, image upload, scheduling. Distribution layer for content engine output.
src/actions/blotato/publish.jsElevenLabs real-time voice AI — patients call and talk to Karen.
Same AI brain as chat but voice-optimized prompt. Books appointments, escalates complex questions to staff via Telegram.
src/webhooks/voice.js → handleElevenLabsTool()Automated lead nurture and re-engagement sequences.
5-touch warm lead sequence over 14 days. No-show recovery. Lapsed patient outreach. Auto-cancels if lead books. Preference learning adapts messaging.
src/nurture.js → enrollContact()Primary data store — 90+ tables. Contacts, conversations, care plans, billing, analytics.
Container: iv_postgres, db: irievybz_core, user: irievybz. pgvector extension for semantic memory search. 33 migration files.
Job queue for all scheduled work — care plan steps, nurture sequences, watchdog checks, content pipeline.
Container: iv_redis. BullMQ handles delayed jobs, retries, and prioritization.
Sensitive medical data stored separately — DPA 2020 compliant.
Path: /opt/irievybz/data/oshun-phi/photos. Hetzner VPS, ready for AWS migration. Intake forms, consent records, clinical photos.
The timeline every lead follows if they become a patient. Each dot is an automated step — nobody on staff has to remember.
If the patient no-shows or goes quiet, they loop back into the nurture sequence (Journey 5). If they ever report a concern during post-care, Karen escalates to Dr. Rockhead on Telegram.
Follow the data through the system, step by step. Open any to see the plumbing.