Twilio WhatsApp Integration

Complete developer guide for the MedSync × Twilio WhatsApp messaging system.

MedSync uses Twilio's WhatsApp Business API to let clinics communicate with patients over WhatsApp. This covers appointment booking (via an AI-powered conversational bot), outbound messages, appointment reminders, bundle (bulk) messaging, and delivery tracking.

Architecture

High-Level Flow

Component Diagram

backend/
  main.py              ← Inbound webhook: POST /api/webhooks/whatsapp
  whatsapp.py          ← Twilio signature verification, Gemini intent parsing, reply generation
  twilio_client.py     ← Twilio REST client (master + subaccount support)
  reminders.py         ← Background loop: appointment reminder sending
  routers/
    whatsapp.py        ← All WhatsApp REST API endpoints (send, conversations, templates, bundle, provision, etc.)
  database/
    __init__.py        ← whatsapp_senders, whatsapp_conversations, whatsapp_messages tables

frontend/
  whatsapp.jsx         ← WhatsApp inbox UI (Conversations + Bundle messages tabs)

How Routing Works

MedSync supports multiple clinics (workspaces), each with its own WhatsApp sender number. When Twilio delivers an inbound message, the To field identifies which clinic the message is for:

1. Twilio POSTs to /api/webhooks/whatsapp with From (patient) and To (clinic sender number)
2. MedSync looks up the sender by the To number in the whatsapp_senders table
3. The sender's account_id determines which workspace (clinic) owns this conversation
4. The patient is upserted into that workspace's patient list

Key Concepts

Setup Guide

1. Environment Variables

Set these on your server (or in .env for local dev):

2. Register a WhatsApp Sender on Twilio

This is a manual process — it cannot be automated from MedSync.

1. Go to Twilio Console → Messaging → Senders → WhatsApp senders
2. Click "Create new sender"
3. Choose your number:
   • Twilio phone number: select an existing Twilio number from the dropdown
   • My own phone number: enter an external number in E.164 format (e.g. +919495476775). You'll verify it via SMS or phone call.
4. Click Continue to proceed to the Facebook Embedded Signup flow
5. In the Facebook popup:
   • Select your Business portfolio (or create one)
   • IMPORTANT: If you already have a WABA connected to your Twilio account, you must select the existing one. Twilio shows a warning with the WABA ID — selecting a different one will cause rejection.
   • Add your phone number and verify via SMS/call
   • Set a display name (must match your business name per Meta guidelines)
6. Complete the flow. The sender will appear as "Online" in the Twilio Console.

3. Configure Webhooks on Twilio

After the sender is registered, configure the webhook URLs:

1. Go to Twilio Console → WhatsApp senders → click "Edit Sender" on your number
2. Set these fields:

   Field	Value
   Webhook URL for incoming messages	https://your-domain.com/api/webhooks/whatsapp
   Webhook method	HTTP Post
   Status callback URL	https://your-domain.com/api/webhooks/whatsapp/status

3. Click "Update WhatsApp Sender"

4. Link the Sender to a MedSync Workspace

There are three ways to connect a WhatsApp number to a MedSync workspace:

Option A: Link Existing (recommended)

For numbers already registered on Twilio as WhatsApp senders:

POST /api/whatsapp/link-existing
Authorization: Bearer <token>
X-Account-Id: <workspace_id>

{
  "phone_number": "+15559913949",
  "display_name": "My Clinic"
}

This saves the number in the whatsapp_senders table for that workspace. Messages from Twilio with To=whatsapp:+15559913949 will route to this workspace.

Option B: Auto-Provision

Creates a Twilio subaccount, buys a US number, and configures webhooks automatically:

POST /api/whatsapp/provision
{
  "clinic_name": "Downtown Clinic",
  "country": "US",
  "area_code": "415"
}

Option C: Manual Entry (Settings UI)

In the MedSync app: go to Settings → Clinic → WhatsApp Number and enter the number. This simply stores the string — no Twilio integration is created. Use "Link Existing" for proper integration.

Message Flow

Inbound Messages (Patient → Clinic)

1. Patient sends WhatsApp message to clinic's registered number
2. Twilio receives it and POSTs to: POST /api/webhooks/whatsapp
   Body: application/x-www-form-urlencoded
   Fields: From, To, Body, ProfileName, MessageSid, etc.
   Header: X-Twilio-Signature (HMAC-SHA1)

3. MedSync verifies Twilio signature (master token, then subaccount token fallback)
4. Routes to workspace by looking up the `To` number in whatsapp_senders
5. Upserts the patient by phone number (creates if new, sets consent_whatsapp=True)
6. Records the inbound message in whatsapp_messages table
7. Checks for slot shortcuts (patient replied "1", "2", or a time like "9:00")
   - If match: resolves directly, skips AI
8. Otherwise: sends conversation history (last 8 messages) + available slots to Gemini
9. Gemini returns a natural-language reply + optional structured intent (book, cancel, etc.)
10. If intent = book: creates appointment with status "pending_review"
11. Returns TwiML <Message> with the reply text
12. Twilio delivers the reply to the patient

Outbound Messages (Clinic → Patient)

1. Doctor opens WhatsApp inbox in MedSync, selects a conversation, types a reply
2. Frontend calls: POST /api/whatsapp/send
   { "patient_id": "...", "body": "Hello!" }

3. Backend looks up the workspace's primary sender (from whatsapp_senders)
4. Calls twilio_client.send_whatsapp() which:
   - Resolves the correct Twilio client (subaccount or master)
   - Adds "whatsapp:" prefix to both To and From numbers
   - Calls Twilio messages.create()
5. Records the outbound message in whatsapp_messages
6. Twilio delivers to patient via WhatsApp

Status Callbacks

Twilio POSTs delivery status updates to /api/webhooks/whatsapp/status:

The callback updates the message status in whatsapp_messages via provider_message_id (Twilio's MessageSid).

API Reference

Multi-Clinic Setup

Each MedSync workspace (clinic) can have its own dedicated WhatsApp number. This provides:

• Separate conversations per clinic
• Clinic-specific auto-replies and branding
• Optional billing isolation via Twilio subaccounts

How It Works

1. Each workspace stores its sender(s) in the whatsapp_senders table with account_id
2. The first sender is marked is_primary=true — this is the default "From" number for outbound messages
3. Up to 3 active senders per workspace
4. Inbound messages are routed by the To number to the correct workspace

Subaccount Credentials (Optional)

If a workspace has its own Twilio subaccount, the subaccount SID and auth token are stored Fernet-encrypted in the whatsapp_senders table (twilio_subaccount_sid, twilio_subaccount_token).

When sending outbound messages, twilio_client.get_client_for_account() checks if the primary sender has subaccount credentials. If yes, it uses a subaccount Twilio client; otherwise falls back to the master client.

Signature Verification for Subaccounts

Twilio signs webhook requests with the auth token of the account that owns the number. For subaccount numbers, the master token won't verify. The inbound webhook handler tries:

1. Master auth token
2. If that fails: look up the sender by To number, decrypt its subaccount token, verify with that

WhatsApp Bot (Gemini-Powered)

When a patient messages the clinic, the bot uses Gemini 2.5 Flash to generate contextual, natural-language replies in the patient's language.

How It Works

1. Conversation history (last 8 messages) is loaded from the database
2. Available appointment slots are fetched via get_available_slots()
3. A prompt is sent to Gemini with: conversation history, available slots, clinic info, current date/time
4. Gemini returns a JSON response with: reply (text to send), intent (book/cancel/question/greeting/farewell), and optionally selected_slot
5. If the intent is book and a slot is selected: an appointment is created with status=pending_review

Slot Shortcuts

For faster booking, patients can reply with just a number ("1", "2") or a time ("9:00", "10:30"). These bypass Gemini entirely and resolve via whatsapp.resolve_slot_reply().

Appointment Status

• WhatsApp-booked appointments start as pending_review
• Doctors accept/reject via the WhatsApp inbox or notifications
• Accept → confirmed + sends WhatsApp confirmation to patient
• Reject → cancelled + sends rejection message

Appointment Reminders

A background task (backend/reminders.py) runs every 5 minutes and sends WhatsApp reminders for upcoming appointments.

Configuration

Per workspace, configurable via Settings → WhatsApp → Reminder Settings or the API:

How It Works

1. Every 5 minutes, queries all workspaces with reminders.enabled=true
2. For each workspace, finds appointments in the upcoming window (now to now + hours_before)
3. Checks that the appointment hasn't already been reminded
4. Sends the reminder via the workspace's primary WhatsApp sender
5. Records the reminder in the database to prevent duplicates

Bundle Messaging

Clinics can send messages to multiple patients at once (up to 250 per batch).

Two Input Methods

• File upload: Upload a .csv or .xlsx file with name and phone columns. Preview with POST /api/whatsapp/bundle/preview.
• Manual entry: Type phone numbers directly in the "Type numbers" tab in the frontend.

Sending

POST /api/whatsapp/bundle/send
{
  "body": "Hi {name}, your appointment is tomorrow at {time}.",
  "recipients": [
    { "name": "John", "phone": "+1234567890", "fields": { "time": "9:00 AM" } },
    { "name": "Maria", "phone": "+0987654321", "fields": { "time": "10:30 AM" } }
  ],
  "consent_confirmed": true
}

The body supports {variable} placeholders resolved per-recipient from name, phone, language, and any extra fields.

Message Templates

MedSync Templates (In-App)

Defined statically in backend/routers/whatsapp.py in the WHATSAPP_TEMPLATES list. These are not Meta-approved templates — they're convenience templates for the MedSync UI that generate freeform message bodies.

Meta Content Templates (Twilio)

For business-initiated messages outside the 24-hour window, you need Meta-approved content templates. These are managed in Twilio Console → Content Template Builder.

To send a Twilio content template via API:

# Python example using Twilio SDK
client.messages.create(
    to="whatsapp:+1234567890",
    from_="whatsapp:+15558887292",
    content_sid="HX9ad6e4a83ef8200679db77af28c4a121",  # template SID
    content_variables=json.dumps({"1": "John", "2": "My Clinic", "3": "May 15, 2:00 PM"})
)

Troubleshooting

Database Schema

whatsapp_senders

Each row is a WhatsApp-registered phone number linked to a workspace.

whatsapp_senders
├── id                      TEXT PRIMARY KEY
├── account_id              TEXT (FK → accounts.id)
├── phone_number            TEXT (e.g., "+15558887292")
├── provider                TEXT (always "twilio")
├── provider_sender_id      TEXT (Twilio Phone SID, e.g., "PNxxx")
├── display_name            TEXT
├── status                  TEXT ("active" | "disabled")
├── is_primary              BOOLEAN
├── twilio_subaccount_sid   TEXT (Fernet-encrypted, optional)
├── twilio_subaccount_token TEXT (Fernet-encrypted, optional)
├── twilio_phone_sid        TEXT (optional)
├── created_at              TEXT (ISO 8601)
└── updated_at              TEXT (ISO 8601)

whatsapp_conversations

One per patient-sender pair. Tracks conversation state for the bot.

whatsapp_conversations
├── id                TEXT PRIMARY KEY
├── account_id        TEXT
├── sender_id         TEXT (FK → whatsapp_senders.id)
├── patient_id        TEXT (FK → patients.id)
├── from_number       TEXT
├── to_number         TEXT
├── state             TEXT ("idle" | "awaiting_slot" | "awaiting_confirm" | ...)
├── pending_intent    TEXT (JSON — stores bot state between messages)
├── last_message_at   TEXT
├── last_inbound_at   TEXT
├── last_outbound_at  TEXT
├── created_at        TEXT
└── updated_at        TEXT

whatsapp_messages

Every inbound and outbound message is recorded here.

whatsapp_messages
├── id                  TEXT PRIMARY KEY
├── account_id          TEXT
├── sender_id           TEXT
├── conversation_id     TEXT (FK → whatsapp_conversations.id)
├── patient_id          TEXT
├── provider            TEXT ("twilio")
├── provider_message_id TEXT (Twilio MessageSid — used for status callback matching)
├── direction           TEXT ("inbound" | "outbound")
├── from_number         TEXT
├── to_number           TEXT
├── body                TEXT
├── status              TEXT ("queued" | "sent" | "delivered" | "read" | "failed")
├── error               TEXT (error details if failed)
├── appointment_id      TEXT (if message is related to an appointment)
├── created_at          TEXT
└── updated_at          TEXT

File Map